Add SEA binary build for packages/server #1449
Open
+592
−5
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Contributor
Greptile SummaryAdds Single Executable Application (SEA) binary build capability for the Stagehand server, enabling client SDKs to spin up a local server without requiring Node.js or repository setup.
Critical issue: Windows workflow builds wrong package ( Minor issue: Error message in Confidence Score: 3/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant GHA as GitHub Actions
participant Deps as Monorepo Dependencies
participant Core as Stagehand Core
participant ESBuild as esbuild
participant Node as Node SEA
participant Postject as postject
participant Binary as Final Binary
GHA->>GHA: Checkout & Setup Node 23
GHA->>Deps: pnpm install --frozen-lockfile
alt Linux/macOS
GHA->>Core: pnpm build:binary (scripts/build.sh)
Core->>Deps: pnpm install
Core->>Core: pnpm --filter @browserbasehq/stagehand build
Core->>ESBuild: Bundle src/server.ts → dist/sea/bundle.cjs
ESBuild-->>Core: bundle.cjs created
Core->>Node: node --experimental-sea-config sea-config.json
Node-->>Core: sea-prep.blob generated
Core->>Postject: scripts/create-binary.sh
Postject->>Postject: Copy node binary
Postject->>Postject: Inject SEA blob (platform-specific)
alt macOS
Postject->>Postject: codesign --remove-signature
Postject->>Postject: Inject with --macho-segment-name
Postject->>Postject: codesign --sign -
else Linux
Postject->>Postject: Inject with sentinel fuse
end
Postject-->>Binary: stagehand-{platform}-{arch}
else Windows
GHA->>Core: pnpm --filter @browserbasehq/stagehand build
GHA->>ESBuild: Bundle src/server.ts → dist/sea/bundle.cjs
ESBuild-->>GHA: bundle.cjs created
GHA->>Node: node --experimental-sea-config sea-config.json
Node-->>GHA: sea-prep.blob generated
GHA->>Postject: Inject blob into node.exe copy
Postject-->>Binary: stagehand-win32-x64.exe
end
GHA->>GHA: Upload artifact (30 day retention)
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
1 issue found across 6 files
Prompt for AI agents (all issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="packages/server/scripts/create-binary.sh">
<violation number="1" location="packages/server/scripts/create-binary.sh:83">
P1: Cross-compilation is broken: the script accepts a target platform argument but always copies the local `node` binary regardless of the specified platform. Running `./create-binary.sh linux-x64` on macOS would produce a macOS binary incorrectly named for Linux.
Consider either:
1. Removing cross-compilation support and validating the platform matches the host
2. Downloading the correct Node.js binary for the target platform from nodejs.org</violation>
</file>
Architecture diagram
sequenceDiagram
participant CI as "GitHub Actions\n(Matrix Strategy)"
participant Script as "Build Scripts\n(Bash/PowerShell)"
participant Bundler as "esbuild / Node\n(Compiler)"
participant Injector as "postject / codesign\n(Packager)"
participant Artifacts as "GitHub Artifacts"
Note over CI, Artifacts: NEW: Build process triggers on push to main
loop Per Platform (Linux, Win, Mac-x64, Mac-ARM)
CI->>Script: Run Build Step
Note right of CI: Matrix injects variables\n(os, arch, binary_name)
%% Dependency Phase
Script->>Script: Install Deps & Build Core (@browserbasehq/stagehand)
%% Bundling Phase
Script->>Bundler: NEW: Run esbuild (src/server.ts)
Bundler-->>Script: Generate dist/sea/bundle.cjs
Script->>Bundler: NEW: Node --experimental-sea-config
Note right of Bundler: Reads sea-config.json
Bundler-->>Script: Generate dist/sea/sea-prep.blob
%% Binary Creation Phase
Script->>Script: Copy local 'node' executable to dist/
alt Platform is MacOS
Script->>Injector: codesign --remove-signature
end
Script->>Injector: NEW: Inject Blob into Node Binary
Note right of Injector: Uses "postject" to write\nblob into binary segment
Script->>Injector: Set Sentinel Fuse
Note right of Injector: NODE_SEA_FUSE_...
alt Platform is MacOS
Script->>Injector: codesign --sign - (Re-sign)
end
%% Validation Phase
alt Blob or Binary Missing
Script-->>CI: Exit Code 1 (Failure)
else Success
Script-->>CI: Binary Created (stagehand-platform-arch)
end
%% Upload Phase
CI->>Artifacts: Upload Release Artifact
end
Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR
pirate
reviewed
Dec 20, 2025
Comment on lines
+14
to
+32
| - os: ubuntu-latest | ||
| platform: linux | ||
| arch: x64 | ||
| binary_name: stagehand-linux-x64 | ||
|
|
||
| - os: macos-latest | ||
| platform: darwin | ||
| arch: arm64 | ||
| binary_name: stagehand-darwin-arm64 | ||
|
|
||
| - os: macos-13 | ||
| platform: darwin | ||
| arch: x64 | ||
| binary_name: stagehand-darwin-x64 | ||
|
|
||
| - os: windows-latest | ||
| platform: win32 | ||
| arch: x64 | ||
| binary_name: stagehand-win32-x64.exe |
Member
There was a problem hiding this comment.
need both arm64 and amd64 for windows and linux too
pirate
approved these changes
Dec 20, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
why
We want a standalone stagehand server executable so client SDKs can spin up a local server without needing Node + the repo setup.
what changed
Adds a
pnpm build:binarypipeline in packages/server that bundles + generates a SEA blob + injects it into a Node binary, and a GitHub Actions matrix workflow that builds one binary per platform and uploads them as artifacts after merges to main.test plan
None
Summary by cubic
Adds a SEA-based standalone Stagehand server binary and a CI workflow to build per-platform executables. This lets client SDKs run a local server without installing Node or checking out the repo.
Written for commit 34bbd82. Summary will update automatically on new commits.