From 5dadc3f3c994e189dc9a5de13a2dae10cf5bf6a7 Mon Sep 17 00:00:00 2001 From: miguel Date: Wed, 19 Aug 2026 15:07:43 -0700 Subject: [PATCH 1/3] docs(integrations): project id optional everywhere; package overview README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BROWSERBASE_PROJECT_ID is optional now (API key is the only required Browserbase credential) — env tables and setup blocks updated across the example READMEs. The package README gains a structure overview with a one-line description per subdirectory. --- packages/integrations/README.md | 27 ++++++++++++++++++--- packages/integrations/claude-code/README.md | 4 +-- packages/integrations/codex/README.md | 4 +-- packages/integrations/crewai/README.md | 2 +- packages/integrations/mastra/README.md | 2 +- packages/integrations/pi/README.md | 2 +- packages/integrations/vercel-ai/README.md | 2 +- 7 files changed, 31 insertions(+), 12 deletions(-) diff --git a/packages/integrations/README.md b/packages/integrations/README.md index 2f732561db..0472f81470 100644 --- a/packages/integrations/README.md +++ b/packages/integrations/README.md @@ -1,8 +1,27 @@ # Stagehand integrations -Private workspace package for Stagehand integration adapters. +Agent-harness integrations for the Stagehand facade tool surface: three tools — `run`, +`snapshot`, and `screenshot` — backed by one persistent browser, consumable either as a stdio +MCP server or as native in-process tools. The contract (tool descriptions, schemas, runtime +validators, and the agent system prompt) is defined once in `core/` and imported everywhere +else, never restated. -The code-mode stdio entrypoint currently provides the MCP host and process lifecycle used by later code-mode capabilities. It intentionally advertises no tools yet. +## Structure -The `deepagents/` Python project provides local and managed LangChain Deep Agents integrations. Both -expose stateful `run`, `snapshot`, and `screenshot` browser tools using the Stagehand Python SDK. +| Directory | What it is | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `core/` | The `@browserbasehq/stagehand-integrations` package: the facade contract, `StagehandFacadeTools`, the `stagehand-facade` stdio MCP bin, and the code-mode MCP host scaffold. | +| `claude-code/` | Claude Agent SDK example (programmatic MCP mount) plus a `.mcp.json` for connecting a running Claude Code CLI. | +| `codex/` | Codex SDK example (config-override MCP mount) plus a `config.toml` template for the codex CLI. | +| `crewai/` | Python CrewAI example over MCP/stdio (uv project). | +| `deepagents/` | Python LangChain Deep Agents integrations: a local stdio MCP server and a Managed Deep Agents project with native tools. | +| `eve/` | Eve example with the tools bound natively via `defineTool` (Eve has no external-process tool mounting). | +| `fx/` | fx configuration templates and skill — fx consumes the facade via its user-global MCP config. | +| `mastra/` | Mastra example over MCP/stdio via Mastra's `MCPClient`. | +| `pi/` | pi extension registering the tools natively (pi ships without built-in MCP). | +| `vercel-ai/` | Vercel AI SDK example over MCP/stdio via `createMCPClient`. | + +Each example is a self-contained project: install, export `BROWSERBASE_API_KEY` +(`BROWSERBASE_PROJECT_ID` is optional), and run — see the directory's README. TypeScript +examples consume `core/` as a workspace dependency; the Python projects resolve the published +`stagehand` package. diff --git a/packages/integrations/claude-code/README.md b/packages/integrations/claude-code/README.md index e8e631a2fb..cc8d968efb 100644 --- a/packages/integrations/claude-code/README.md +++ b/packages/integrations/claude-code/README.md @@ -18,7 +18,7 @@ Export credentials (Browserbase is the default and recommended backend): ```bash export ANTHROPIC_API_KEY=sk-ant-... export BROWSERBASE_API_KEY=bb_live_... -export BROWSERBASE_PROJECT_ID=... +export BROWSERBASE_PROJECT_ID=... # optional ``` ## Run @@ -31,7 +31,7 @@ pnpm --filter @browserbasehq/stagehand-integrations-example-claude-code-facade s | ------------------------ | ------------------------------------------------------------------------------------------------ | | `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. | | `BROWSERBASE_API_KEY` | Browserbase credential for the browser session. | -| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project. | +| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | | `CLAUDE_STAGEHAND_MODEL` | Agent model; defaults to `claude-sonnet-5`. | | `ANTHROPIC_API_KEY` | Claude Agent SDK credential (never forwarded to the browser). | diff --git a/packages/integrations/codex/README.md b/packages/integrations/codex/README.md index e087ddcdda..3a0e659bdf 100644 --- a/packages/integrations/codex/README.md +++ b/packages/integrations/codex/README.md @@ -21,7 +21,7 @@ Export credentials (Browserbase is the default and recommended backend). Codex a ```bash export OPENAI_API_KEY=sk-... export BROWSERBASE_API_KEY=bb_live_... -export BROWSERBASE_PROJECT_ID=... +export BROWSERBASE_PROJECT_ID=... # optional ``` ## Run @@ -34,7 +34,7 @@ pnpm --filter @browserbasehq/stagehand-integrations-example-codex-facade start " | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. | | `BROWSERBASE_API_KEY` | Browserbase credential for the browser session. | -| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project. | +| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | | `CODEX_STAGEHAND_MODEL` | Optional model override; by default Codex uses its own harness-tuned model. | | `OPENAI_API_KEY` | Codex SDK credential (never forwarded to the browser). | | `CODEX_PATH_OVERRIDE` | Path to a locally installed `codex` binary if your package manager skips the SDK's vendored-binary postinstall (`export CODEX_PATH_OVERRIDE=$(which codex)`). | diff --git a/packages/integrations/crewai/README.md b/packages/integrations/crewai/README.md index 8ded014a4e..485f611777 100644 --- a/packages/integrations/crewai/README.md +++ b/packages/integrations/crewai/README.md @@ -25,7 +25,7 @@ uv sync | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. | | `BROWSERBASE_API_KEY` | Browserbase API key. | -| `BROWSERBASE_PROJECT_ID` | Browserbase project ID. | +| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | | `STAGEHAND_MODEL_NAME` / `STAGEHAND_MODEL_API_KEY` | Model used by the facade server and its key. | | `CREWAI_MODEL` | CrewAI agent model; defaults to `openai/gpt-5.6-luna`. | | `OPENAI_API_KEY` | Used by the CrewAI agent model in the host process; NOT forwarded to the facade child process (the child env is an explicit `STAGEHAND_*`/`BROWSERBASE_*` allowlist). | diff --git a/packages/integrations/mastra/README.md b/packages/integrations/mastra/README.md index 64586847b6..cf797e21a6 100644 --- a/packages/integrations/mastra/README.md +++ b/packages/integrations/mastra/README.md @@ -25,7 +25,7 @@ Configure the environment as needed: | ------------------------- | ------------------------------------------------------------------------------------------------ | | `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. | | `BROWSERBASE_API_KEY` | Browserbase API key. | -| `BROWSERBASE_PROJECT_ID` | Browserbase project ID. | +| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | | `STAGEHAND_MODEL_NAME` | Model used by the facade server. | | `STAGEHAND_MODEL_API_KEY` | API key for the facade server model. | | `MASTRA_STAGEHAND_MODEL` | Mastra agent model; defaults to `gpt-5.6-luna`. | diff --git a/packages/integrations/pi/README.md b/packages/integrations/pi/README.md index e4124a2843..667038750d 100644 --- a/packages/integrations/pi/README.md +++ b/packages/integrations/pi/README.md @@ -19,7 +19,7 @@ key pi supports: ```bash export BROWSERBASE_API_KEY=bb_live_... -export BROWSERBASE_PROJECT_ID=... +export BROWSERBASE_PROJECT_ID=... # optional export OPENAI_API_KEY=sk-... # or ANTHROPIC_API_KEY ``` diff --git a/packages/integrations/vercel-ai/README.md b/packages/integrations/vercel-ai/README.md index f5166b1779..dc28488e79 100644 --- a/packages/integrations/vercel-ai/README.md +++ b/packages/integrations/vercel-ai/README.md @@ -26,7 +26,7 @@ Configure the environment as needed: | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. | | `BROWSERBASE_API_KEY` | Browserbase API key. | -| `BROWSERBASE_PROJECT_ID` | Browserbase project ID. | +| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | | `STAGEHAND_MODEL_NAME` | Model used by the facade server. | | `STAGEHAND_MODEL_API_KEY` | API key for the facade server model. | | `AI_SDK_STAGEHAND_MODEL` | AI SDK agent model; defaults to `gpt-5.6-luna`. | From 623ee201fc35966c1c5da036d14bf7e3a635af4a Mon Sep 17 00:00:00 2001 From: miguel Date: Wed, 19 Aug 2026 15:08:12 -0700 Subject: [PATCH 2/3] docs(integrations): Pi casing in overview table --- packages/integrations/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/integrations/README.md b/packages/integrations/README.md index 0472f81470..e62024373a 100644 --- a/packages/integrations/README.md +++ b/packages/integrations/README.md @@ -18,7 +18,7 @@ else, never restated. | `eve/` | Eve example with the tools bound natively via `defineTool` (Eve has no external-process tool mounting). | | `fx/` | fx configuration templates and skill — fx consumes the facade via its user-global MCP config. | | `mastra/` | Mastra example over MCP/stdio via Mastra's `MCPClient`. | -| `pi/` | pi extension registering the tools natively (pi ships without built-in MCP). | +| `pi/` | Pi extension registering the tools natively (Pi ships without built-in MCP). | | `vercel-ai/` | Vercel AI SDK example over MCP/stdio via `createMCPClient`. | Each example is a self-contained project: install, export `BROWSERBASE_API_KEY` From 3e7c0c56436a0deb0cc0baa15f3d408f653fe0ff Mon Sep 17 00:00:00 2001 From: miguel Date: Wed, 19 Aug 2026 15:16:28 -0700 Subject: [PATCH 3/3] docs(integrations): drop project id from READMEs entirely --- packages/integrations/README.md | 5 ++--- packages/integrations/claude-code/README.md | 2 -- packages/integrations/codex/README.md | 16 +++++++--------- packages/integrations/crewai/README.md | 1 - packages/integrations/eve/README.md | 1 - packages/integrations/mastra/README.md | 1 - packages/integrations/pi/README.md | 1 - packages/integrations/vercel-ai/README.md | 1 - 8 files changed, 9 insertions(+), 19 deletions(-) diff --git a/packages/integrations/README.md b/packages/integrations/README.md index e62024373a..00665ba3d0 100644 --- a/packages/integrations/README.md +++ b/packages/integrations/README.md @@ -21,7 +21,6 @@ else, never restated. | `pi/` | Pi extension registering the tools natively (Pi ships without built-in MCP). | | `vercel-ai/` | Vercel AI SDK example over MCP/stdio via `createMCPClient`. | -Each example is a self-contained project: install, export `BROWSERBASE_API_KEY` -(`BROWSERBASE_PROJECT_ID` is optional), and run — see the directory's README. TypeScript -examples consume `core/` as a workspace dependency; the Python projects resolve the published +Each example is a self-contained project: install, export `BROWSERBASE_API_KEY`, and run — +see the directory's README. TypeScript examples consume `core/` as a workspace dependency; the Python projects resolve the published `stagehand` package. diff --git a/packages/integrations/claude-code/README.md b/packages/integrations/claude-code/README.md index cc8d968efb..24844712de 100644 --- a/packages/integrations/claude-code/README.md +++ b/packages/integrations/claude-code/README.md @@ -18,7 +18,6 @@ Export credentials (Browserbase is the default and recommended backend): ```bash export ANTHROPIC_API_KEY=sk-ant-... export BROWSERBASE_API_KEY=bb_live_... -export BROWSERBASE_PROJECT_ID=... # optional ``` ## Run @@ -31,7 +30,6 @@ pnpm --filter @browserbasehq/stagehand-integrations-example-claude-code-facade s | ------------------------ | ------------------------------------------------------------------------------------------------ | | `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. | | `BROWSERBASE_API_KEY` | Browserbase credential for the browser session. | -| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | | `CLAUDE_STAGEHAND_MODEL` | Agent model; defaults to `claude-sonnet-5`. | | `ANTHROPIC_API_KEY` | Claude Agent SDK credential (never forwarded to the browser). | diff --git a/packages/integrations/codex/README.md b/packages/integrations/codex/README.md index 3a0e659bdf..8b1dfc4721 100644 --- a/packages/integrations/codex/README.md +++ b/packages/integrations/codex/README.md @@ -21,7 +21,6 @@ Export credentials (Browserbase is the default and recommended backend). Codex a ```bash export OPENAI_API_KEY=sk-... export BROWSERBASE_API_KEY=bb_live_... -export BROWSERBASE_PROJECT_ID=... # optional ``` ## Run @@ -30,14 +29,13 @@ export BROWSERBASE_PROJECT_ID=... # optional pnpm --filter @browserbasehq/stagehand-integrations-example-codex-facade start "Open https://example.com, snapshot it, and report the heading citing the snapshot ID." ``` -| Variable | Purpose | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. | -| `BROWSERBASE_API_KEY` | Browserbase credential for the browser session. | -| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | -| `CODEX_STAGEHAND_MODEL` | Optional model override; by default Codex uses its own harness-tuned model. | -| `OPENAI_API_KEY` | Codex SDK credential (never forwarded to the browser). | -| `CODEX_PATH_OVERRIDE` | Path to a locally installed `codex` binary if your package manager skips the SDK's vendored-binary postinstall (`export CODEX_PATH_OVERRIDE=$(which codex)`). | +| Variable | Purpose | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. | +| `BROWSERBASE_API_KEY` | Browserbase credential for the browser session. | +| `CODEX_STAGEHAND_MODEL` | Optional model override; by default Codex uses its own harness-tuned model. | +| `OPENAI_API_KEY` | Codex SDK credential (never forwarded to the browser). | +| `CODEX_PATH_OVERRIDE` | Path to a locally installed `codex` binary if your package manager skips the SDK's vendored-binary postinstall (`export CODEX_PATH_OVERRIDE=$(which codex)`). | The local sandbox stays `read-only` — all browser work happens inside the MCP server. Note Codex has no native turn limit; long tasks run until the model finishes. diff --git a/packages/integrations/crewai/README.md b/packages/integrations/crewai/README.md index 485f611777..9474578102 100644 --- a/packages/integrations/crewai/README.md +++ b/packages/integrations/crewai/README.md @@ -25,7 +25,6 @@ uv sync | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. | | `BROWSERBASE_API_KEY` | Browserbase API key. | -| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | | `STAGEHAND_MODEL_NAME` / `STAGEHAND_MODEL_API_KEY` | Model used by the facade server and its key. | | `CREWAI_MODEL` | CrewAI agent model; defaults to `openai/gpt-5.6-luna`. | | `OPENAI_API_KEY` | Used by the CrewAI agent model in the host process; NOT forwarded to the facade child process (the child env is an explicit `STAGEHAND_*`/`BROWSERBASE_*` allowlist). | diff --git a/packages/integrations/eve/README.md b/packages/integrations/eve/README.md index fe8d49c183..50a35634e8 100644 --- a/packages/integrations/eve/README.md +++ b/packages/integrations/eve/README.md @@ -18,7 +18,6 @@ Configure the environment as needed: | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. | | `BROWSERBASE_API_KEY` | Browserbase API key; required when using the Browserbase backend. | -| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | | `STAGEHAND_MODEL_NAME` | Optional Stagehand model name, such as `openai/gpt-5.6-luna`. | | `STAGEHAND_MODEL_API_KEY` | Optional explicit API key for `STAGEHAND_MODEL_NAME`; otherwise the matching provider key is inferred when supported. | | `STAGEHAND_EVE_SESSION_FILE` | Optional path used to persist the Browserbase session ID; defaults to a file in the system temporary directory. | diff --git a/packages/integrations/mastra/README.md b/packages/integrations/mastra/README.md index cf797e21a6..8b2e03da8f 100644 --- a/packages/integrations/mastra/README.md +++ b/packages/integrations/mastra/README.md @@ -25,7 +25,6 @@ Configure the environment as needed: | ------------------------- | ------------------------------------------------------------------------------------------------ | | `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. | | `BROWSERBASE_API_KEY` | Browserbase API key. | -| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | | `STAGEHAND_MODEL_NAME` | Model used by the facade server. | | `STAGEHAND_MODEL_API_KEY` | API key for the facade server model. | | `MASTRA_STAGEHAND_MODEL` | Mastra agent model; defaults to `gpt-5.6-luna`. | diff --git a/packages/integrations/pi/README.md b/packages/integrations/pi/README.md index 667038750d..3f98bfb900 100644 --- a/packages/integrations/pi/README.md +++ b/packages/integrations/pi/README.md @@ -19,7 +19,6 @@ key pi supports: ```bash export BROWSERBASE_API_KEY=bb_live_... -export BROWSERBASE_PROJECT_ID=... # optional export OPENAI_API_KEY=sk-... # or ANTHROPIC_API_KEY ``` diff --git a/packages/integrations/vercel-ai/README.md b/packages/integrations/vercel-ai/README.md index dc28488e79..cddecbd05a 100644 --- a/packages/integrations/vercel-ai/README.md +++ b/packages/integrations/vercel-ai/README.md @@ -26,7 +26,6 @@ Configure the environment as needed: | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `STAGEHAND_BROWSER` | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`. | | `BROWSERBASE_API_KEY` | Browserbase API key. | -| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | | `STAGEHAND_MODEL_NAME` | Model used by the facade server. | | `STAGEHAND_MODEL_API_KEY` | API key for the facade server model. | | `AI_SDK_STAGEHAND_MODEL` | AI SDK agent model; defaults to `gpt-5.6-luna`. |