feat: add Stagehand code-mode MCP image

[shrey150]

Why

Stagehand code mode evaluates model-generated JavaScript. A normal host process or standalone container is not a sufficient boundary for untrusted code because that code inherits the process's filesystem, environment, and network access.

This layer packages the canonical stdio MCP server as an unprivileged OCI image and documents how to run that image inside a Firecracker microVM or equivalent sandbox. The image is portable packaging; the sandbox provider supplies the security boundary.

Relationship to the framework stack

#2620 remains the common parent for two independent paths:

• #2626 source-installs the pinned Stagehand MCP inside E2B and is the required sandbox foundation for framework integrations.
• This PR provides an optional OCI package for faster startup and portability across providers.

The framework PRs do not need this image to merge. E2B can clone, install, and build the exact pinned Stagehand source inside its Firecracker microVM. This PR can land independently when its publishing and provenance workflow is ready.

What changed

• adds a multi-stage Dockerfile.codemode that builds the exact workspace implementation and runs the stdio server as the non-root node user
• keeps the runtime command overrideable so sandbox providers can start a trusted bridge in the same guest when an outside framework needs Streamable HTTP
• adds a fork-safe GitHub Actions build and network-disabled MCP discovery smoke
• publishes immutable SHA and prerelease tags to ghcr.io/browserbase/stagehand-codemode only on an explicit tag or manual publish; it never publishes latest
• attaches GitHub build-provenance attestations to published images
• documents E2B, Modal, Vercel Sandbox, Codex, and Claude Code layouts, including credential allowlists, egress policy, deadlines, and cleanup

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
docker build --platform linux/amd64 -f Dockerfile.codemode -t stagehand-codemode:foundation .	All four required workspace builds and the production deploy completed. The final image was 87,020,972 bytes.	Proves the source tree under review produces the proposed runtime image on the architecture required by Modal.
External MCP SDK spawning docker run --rm -i --network none --platform linux/amd64 stagehand-codemode:foundation	{"status":"PASS","network":"none","tools":["code_execute"]}	Proves a real stdio MCP client can start the image and discover exactly code_execute without network access.
Runtime identity inspection	The final image reported node as its user and Node.js 24.19.0 as its runtime.	Proves the runtime drops root privileges and uses the pinned Node base selected by the Dockerfile.
Workflow and secret scan	All third-party actions are commit-pinned; publish permissions exist only on tag/manual publish; no embedded credentials were found.	Proves the PR build remains read-only and the checked-in image inputs do not contain secrets.

The discovery smoke intentionally does not execute browser code because it runs with --network none. The downstream framework PRs carry the live Browserbase and sandbox-containment proofs.

Changeset

None. This adds packaging, documentation, and CI without changing a published package API or runtime default.

[changeset-bot]

⚠️ No Changeset found

Latest commit: e4bbe74

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

All reported issues were addressed across 5 files

Architecture diagram

sequenceDiagram
    participant Host as Agent Application
    participant MCP as Sandbox MCP Gateway
    participant MicroVM as Firecracker MicroVM
    participant Stdio as Stagehand Code-Mode MCP (Stdio)
    participant JS as Generated JavaScript (Untrusted)
    participant Reg as GHCR Container Registry
    participant CI as CI Pipeline

    Note over Host,MicroVM: PR introduces sandboxed OCI image architecture

    %% Build Phase
    CI->>CI: Build multi-stage Dockerfile.codemode
    CI->>Reg: Publish immutable sha-<commit> tags
    CI->>Reg: Attach build-provenance attestation
    Reg-->>CI: Image available at ghcr.io/browserbase/stagehand-codemode

    %% Image Pull and Deployment
    Host->>Reg: Pull image by digest (sha-<commit>)
    Reg-->>Host: Stagehand code-mode OCI image
    Host->>MicroVM: Launch Firecracker microVM with image
    Host->>MicroVM: Pass only BROWSERBASE_API_KEY & PROJECT_ID

    %% Runtime Flow Inside Sandbox
    MicroVM->>Stdio: Start stdio-server.mjs as non-root "node" user
    Host->>MCP: Authenticated Streamable HTTP request
    MCP->>MicroVM: Forward MCP request via stdio
    MicroVM->>Stdio: Route to Stagehand MCP server
    Stdio->>Stdio: Initialize with protocolVersion "2025-06-18"

    alt Code Execution Request
        Stdio->>Stdio: tools/list response: ["code_execute"]
        Host->>MCP: Invoke code_execute tool
        MCP->>MicroVM: Forward invocation
        MicroVM->>Stdio: Execute generated JavaScript
        Stdio->>JS: Evaluate untrusted code
        JS-->>Stdio: Execution result
        Stdio->>Stdio: Run Stagehand browser actions
        Stdio-->>MicroVM: Return result
        MicroVM-->>MCP: Stream response back
        MCP-->>Host: Tool execution output

    else Discovery Smoke (CI Phase)
        CI->>Stdio: docker run --network none
        CI->>Stdio: Send initialize & tools/list MCP messages
        Stdio-->>CI: Response with code_execute tool
        note over CI,Stdio: NEW: Network-disabled MCP verification
    end

    %% Cleanup
    Host->>MicroVM: Terminate agent run / timeout
    MicroVM->>Stdio: Close stdin (trigger graceful shutdown)
    MicroVM->>MicroVM: Destroy complete microVM boundary

    Note over Host,Reg: Security boundaries enforced throughout

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[shrey150]

This does not need to land before launch