diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 000000000..2120ece36 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "browserbase-stagehand", + "interface": { + "displayName": "Browserbase Stagehand" + }, + "plugins": [ + { + "name": "stagehand", + "source": { + "source": "local", + "path": "./plugins/stagehand" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} diff --git a/packages/docs/v4/integrations/codex.mdx b/packages/docs/v4/integrations/codex.mdx index d2b110baf..2c4d859b6 100644 --- a/packages/docs/v4/integrations/codex.mdx +++ b/packages/docs/v4/integrations/codex.mdx @@ -3,20 +3,35 @@ title: "Codex" description: "Give a Codex agent persistent Stagehand browser tools over MCP/stdio." --- -The Codex integration gives a Codex agent a persistent Stagehand browser it can drive with `run`, `snapshot`, and `screenshot`. A Codex SDK thread connects to the Stagehand facade MCP server over MCP/stdio, and one server process owns the browser, so page state survives across tool calls. +The Codex plugin gives a Codex agent a persistent Stagehand browser it can drive with `run`, `snapshot`, and `screenshot`. Codex connects to the Stagehand facade MCP server over MCP/stdio, and one server process owns the browser, so page state survives across tool calls. -Stagehand ships this experimental integration from the repository rather than publishing it as a standalone adapter. +The plugin requires the first `@browserbasehq/stagehand-mcp@0.1.0` npm release. Until it is published, use the source example below. -## Prerequisites +## Install the plugin + +```bash +codex plugin marketplace add browserbase/stagehand +codex plugin add stagehand@browserbase-stagehand +``` + +Restart Codex or open a new task after installing. The plugin uses Codex’s [repository marketplace format](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli); it is not a listing in the universal public directory. + +Requires Node.js 24+, an existing Codex login, and local Chrome. To use Browserbase, export `BROWSERBASE_API_KEY` before starting Codex. The plugin passes browser configuration through `env_vars`, so credentials stay out of its manifest. It sets longer startup and tool timeouts for browser work. + +Ask Codex to open `https://example.com`, take a snapshot, and report its title. The plugin provides `run`, `snapshot`, and `screenshot` over one persistent MCP connection. + +The SDK example below is for embedding Codex in an application. + +## Source example prerequisites - Node.js 24 or newer - pnpm 11.10.0 - An OpenAI API key or an existing `codex login` for the example agent - A current Google Chrome installation for local browser mode -## Quickstart +## Run the SDK example from source @@ -74,32 +89,20 @@ The example starts one Codex thread against one facade MCP server, with raised M The MCP child receives only Stagehand and Browserbase configuration plus the process values required to launch Node. The host's model credential remains in the Codex process. -## Connect a running Codex CLI +## Connect the CLI without a plugin -The same server works from the Codex CLI. Merge the package's `config.toml` into `~/.codex/config.toml`, adjusting the path to your checkout: +For a locally built server, merge this into your Codex configuration and adjust the server path: ```toml [mcp_servers.stagehand] command = "node" args = ["/absolute/path/to/stagehand/packages/integrations/core/dist/facade/stdio-server.mjs"] - -[mcp_servers.stagehand.env] -STAGEHAND_BROWSER = "browserbase" -BROWSERBASE_API_KEY = "bb_live_..." -BROWSERBASE_PROJECT_ID = "..." -``` - -Codex does not expand shell variables in config values; paste the real keys or generate this file from your environment. For a one-off run, pass the same values as `codex exec` overrides: - -```bash -codex exec \ - -c mcp_servers.stagehand.command=node \ - -c 'mcp_servers.stagehand.args=["/absolute/path/to/packages/integrations/core/dist/facade/stdio-server.mjs"]' \ - -c 'mcp_servers.stagehand.env={ STAGEHAND_BROWSER = "browserbase", BROWSERBASE_API_KEY = "bb_live_..." }' \ - "your instruction" +env_vars = ["STAGEHAND_BROWSER", "BROWSERBASE_API_KEY", "BROWSERBASE_PROJECT_ID", "STAGEHAND_MODEL_NAME", "STAGEHAND_MODEL_API_KEY"] +startup_timeout_sec = 120 +tool_timeout_sec = 120 ``` -These overrides merge with any `[mcp_servers]` already in your `~/.codex/config.toml` rather than replacing them; set `CODEX_HOME` to a scratch directory if you need isolation. +Export credentials before starting Codex. Avoid keeping real keys in `config.toml` or command-line overrides. Do not enable both this server and the plugin for the same task; each starts its own browser. `run` executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the [integration security boundary](/v4/integrations/overview#security-boundary). diff --git a/packages/docs/v4/integrations/overview.mdx b/packages/docs/v4/integrations/overview.mdx index 9aaee8545..9ccc5ce77 100644 --- a/packages/docs/v4/integrations/overview.mdx +++ b/packages/docs/v4/integrations/overview.mdx @@ -7,9 +7,25 @@ description: "Connect Claude Code, Codex, CrewAI, Deep Agents, Eve, Mastra, fx, Each integration gives your agent one persistent browser and three tools: `run`, `snapshot`, and `screenshot`. Your agent decides how to navigate and interact while Stagehand manages the browser session. -Stagehand ships these experimental integrations from the monorepo and does not publish the adapters or shared integration package as standalone packages. +Distribution follows each host’s supported extension mechanism. Consult the host guide for release availability and source-testing instructions. The shared Core workspace package remains private. +## Supported setup routes + +| Host | Preferred integration mechanism | +| --- | --- | +| Claude Code | A Claude Code marketplace plugin that registers the Stagehand facade MCP server. | +| Codex | A Codex repository marketplace plugin that registers the Stagehand facade MCP server. | +| Pi | A native Pi extension installed with Pi’s package manager. | +| Eve | A native Eve extension mounted in the agent. | +| Mastra | Mastra’s official `MCPClient`, attached as agent tools. | +| Vercel AI SDK | The official `@ai-sdk/mcp` client, attached to the tool loop. | +| CrewAI | Official `MCPServerAdapter` for portable setup; `MCPAdapt` with `CrewAIToolAdapter` for the source example’s screenshot files. | +| Deep Agents | LangChain MCP adapters with a persistent session, or native tools for Managed Deep Agents. | +| fx | fx’s built-in MCP client and `/mcp add` configuration flow. | + +The first four hosts provide plugin or extension distribution. The remaining guides use the host’s supported tool APIs; they do not require a separate marketplace plugin. Packaging varies between the portable facade MCP server, source builds, and the Python-native Deep Agents server. They preserve the same browser tool contract. + ## Choose an integration diff --git a/packages/integrations/codex/README.md b/packages/integrations/codex/README.md index 8b1dfc472..4f790b17b 100644 --- a/packages/integrations/codex/README.md +++ b/packages/integrations/codex/README.md @@ -1,5 +1,14 @@ # Codex SDK + Stagehand facade over MCP/stdio +## Install the Codex plugin + +```sh +codex plugin marketplace add browserbase/stagehand +codex plugin add stagehand@browserbase-stagehand +``` + +Requires the first `@browserbasehq/stagehand-mcp@0.1.0` release. The [repository plugin](../../../plugins/stagehand) supplies the MCP configuration, browser environment allowlist, and timeouts. Restart Codex after installing. Keep browser credentials in the environment. The SDK example below remains available for programmatic use. + A runnable example embedding a Codex agent via `@openai/codex-sdk`, with the Stagehand facade (`run` / `snapshot` / `screenshot`) mounted as a stdio MCP server through the SDK's config override — install, export keys, one line to run. The SDK spawns the bundled Codex runtime; diff --git a/packages/integrations/codex/config.toml b/packages/integrations/codex/config.toml index 86c0b95f4..fc3905aec 100644 --- a/packages/integrations/codex/config.toml +++ b/packages/integrations/codex/config.toml @@ -1,14 +1,14 @@ -# Codex CLI MCP server entry for the Stagehand facade. -# Merge this block into ~/.codex/config.toml (or pass per-invocation with -# `codex -c`), adjusting the absolute path to your checkout. - +# Optional direct CLI configuration; prefer the repository marketplace plugin. +# Adjust the server path and export credentials before starting Codex. [mcp_servers.stagehand] command = "node" args = ["/absolute/path/to/stagehand/packages/integrations/core/dist/facade/stdio-server.mjs"] - -[mcp_servers.stagehand.env] -STAGEHAND_BROWSER = "browserbase" -# Codex does not expand shell variables in config values; paste the real keys -# or generate this file from your environment. -BROWSERBASE_API_KEY = "bb_live_..." -BROWSERBASE_PROJECT_ID = "..." +env_vars = [ + "STAGEHAND_BROWSER", + "BROWSERBASE_API_KEY", + "BROWSERBASE_PROJECT_ID", + "STAGEHAND_MODEL_NAME", + "STAGEHAND_MODEL_API_KEY", +] +startup_timeout_sec = 120 +tool_timeout_sec = 120 diff --git a/plugins/stagehand/.codex-plugin/plugin.json b/plugins/stagehand/.codex-plugin/plugin.json new file mode 100644 index 000000000..8a495cbde --- /dev/null +++ b/plugins/stagehand/.codex-plugin/plugin.json @@ -0,0 +1,21 @@ +{ + "name": "stagehand", + "version": "0.1.0", + "description": "Give Codex a persistent Stagehand browser with run, snapshot, and screenshot tools.", + "author": { + "name": "Browserbase" + }, + "interface": { + "displayName": "Stagehand", + "shortDescription": "Persistent browser tools for Codex", + "developerName": "Browserbase", + "category": "Developer Tools", + "longDescription": "Control a persistent browser using Stagehand run, snapshot, and screenshot tools.", + "defaultPrompt": ["Open https://example.com and report its title."], + "capabilities": ["Read", "Write"] + }, + "mcpServers": "./.mcp.json", + "homepage": "https://docs.stagehand.dev/v4/integrations/codex", + "repository": "https://github.com/browserbase/stagehand", + "license": "MIT" +} diff --git a/plugins/stagehand/.mcp.json b/plugins/stagehand/.mcp.json new file mode 100644 index 000000000..16297076f --- /dev/null +++ b/plugins/stagehand/.mcp.json @@ -0,0 +1,17 @@ +{ + "mcpServers": { + "stagehand": { + "command": "npx", + "args": ["-y", "@browserbasehq/stagehand-mcp@0.1.0"], + "env_vars": [ + "STAGEHAND_BROWSER", + "BROWSERBASE_API_KEY", + "BROWSERBASE_PROJECT_ID", + "STAGEHAND_MODEL_NAME", + "STAGEHAND_MODEL_API_KEY" + ], + "startup_timeout_sec": 120, + "tool_timeout_sec": 120 + } + } +} diff --git a/plugins/stagehand/README.md b/plugins/stagehand/README.md new file mode 100644 index 000000000..11f5fec4a --- /dev/null +++ b/plugins/stagehand/README.md @@ -0,0 +1,12 @@ +# Stagehand for Codex + +```sh +codex plugin marketplace add browserbase/stagehand +codex plugin add stagehand@browserbase-stagehand +``` + +Restart Codex after installation, or open a new task. Requires Node.js 24+, local Chrome or an exported `BROWSERBASE_API_KEY`, and the initial `@browserbasehq/stagehand-mcp@0.1.0` release. This is a repository marketplace plugin, not a claim of listing in OpenAI’s public directory. + +The plugin bundles MCP configuration and forwards only the listed browser configuration variables. Keep credentials in your environment instead of the manifest. It preserves one browser across `run`, `snapshot`, and `screenshot` calls. + +The MCP child receives `STAGEHAND_MODEL_NAME` and `STAGEHAND_MODEL_API_KEY` when you configure them; it does not receive Codex’s provider credential. Plain navigation, snapshots, and screenshots do not require a separate Stagehand model. See the [configuration guide](https://docs.stagehand.dev/v4/integrations/codex#configuration) for optional Stagehand model settings.