feat(codex): add the Stagehand marketplace plugin and setup guide

.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"
+    }
+  ]
+}

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.
 
 <Note>
-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.
 </Note>
 
-## 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
 
 <Steps>
   <Step title="Clone and build Stagehand">
@@ -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.
 
 <Warning>
 `run` executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the [integration security boundary](/v4/integrations/overview#security-boundary).

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.
 
 <Info>
-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.
 </Info>
 
+## 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
 
 <CardGroup cols={2}>

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;

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

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"
+}

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
+    }
+  }
+}

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.