> ## Documentation Index
> Fetch the complete documentation index at: https://docs-preview.webcompute.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables

> Reference Webcompute environment variables for SDK, CLI, MCP, model profiles, local development, and release/runtime behavior.

Environment variables are read by different surfaces. Prefer explicit SDK options or CLI config when you need per-call behavior; use environment variables for process-level configuration and secrets.

## Core client variables

| Variable                | Used by        | Description                                                                                                              |
| ----------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `WEBCOMPUTE_API_KEY`    | SDK, CLI, MCP  | Webcompute API key. Overrides stored CLI config for CLI/MCP. Required by the SDK unless passed as `new Web({ apiKey })`. |
| `WEBCOMPUTE_SERVER_URL` | SDK, CLI, MCP  | Gateway URL. Defaults to `https://api.webcompute.dev`. `http` is accepted only for localhost or loopback.                |
| `WEBCOMPUTE_TIMEOUT`    | TypeScript SDK | Default SDK request timeout in milliseconds. Defaults to `120000`. Non-integer values fall back to the default.          |
| `WEBCOMPUTE_DEBUG`      | SDK, CLI, MCP  | Set to `true` for debug logging and more verbose diagnostics.                                                            |

## MCP variables

Generated MCP host configs prefer CLI args such as
`["mcp", "run", "--surface", "agent", "--model", "browsing"]`. Use these
variables for process-level defaults, secrets, and backward-compatible host
setups. CLI flags override `WEBCOMPUTE_MCP_SURFACE` and
`WEBCOMPUTE_MODEL_PROFILE`.

| Variable                                | Description                                                                                       |
| --------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `WEBCOMPUTE_MCP_SURFACE`                | MCP surface: `runtime`, `agent`, or `all`. Defaults to `runtime`.                                 |
| `WEBCOMPUTE_MCP_DEFAULT_BROWSER_POLICY` | JSON object used as the default browser policy for MCP-created browsers. Must parse to an object. |
| `MCP_TRANSPORT`                         | MCP transport: `stdio` or `http`. Defaults to `stdio`.                                            |
| `MCP_HOST`                              | HTTP bind host. HTTP transport must bind to a loopback host.                                      |
| `MCP_PORT`                              | HTTP port.                                                                                        |
| `PORT`                                  | Fallback HTTP port when `MCP_PORT` is not set. Defaults to `8932`.                                |

## Agent model variables

These variables configure MCP `run_web_agent` when it is enabled on the `agent` or `all` surface. SDK `web.agent()` still requires explicit model config.

| Variable                             | Description                                                                         |
| ------------------------------------ | ----------------------------------------------------------------------------------- |
| `WEBCOMPUTE_MODEL_PROFILE`           | Saved model profile name for MCP `run_web_agent` model selection.                   |
| `WEBCOMPUTE_AGENT_MODEL`             | Direct model ID for MCP `run_web_agent`.                                            |
| `WEBCOMPUTE_AGENT_MODEL_ROUTE`       | Model route: `openai`, `openrouter`, `openai-compatible`, `anthropic`, or `google`. |
| `WEBCOMPUTE_AGENT_MODEL_API_KEY_ENV` | Name of the environment variable containing the model-provider API key.             |
| `WEBCOMPUTE_AGENT_MODEL_BASE_URL`    | Base URL for `openai-compatible` or compatible gateway routes.                      |
| `WEBCOMPUTE_AGENT_MODEL_API`         | Provider API family: `chat-completions` or `responses`.                             |

Common provider credential variables:

| Variable             | Typical use                    |
| -------------------- | ------------------------------ |
| `OPENAI_API_KEY`     | OpenAI route.                  |
| `OPENROUTER_API_KEY` | OpenRouter route.              |
| `ANTHROPIC_API_KEY`  | Anthropic route.               |
| `GEMINI_API_KEY`     | Google Gemini route.           |
| `GOOGLE_API_KEY`     | Google credential alternative. |

Model profiles store these provider credential variable names, not the raw provider key values. The key values are read from the environment at run time.

## CLI local-runtime variables

| Variable                        | Description                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------- |
| `XDG_CONFIG_HOME`               | Overrides config-file base directory.                                                       |
| `XDG_DATA_HOME`                 | Overrides data-file base directory.                                                         |
| `XDG_STATE_HOME`                | Overrides state-file base directory.                                                        |
| `XDG_CACHE_HOME`                | Overrides cache-file base directory.                                                        |
| `OPENCODE_CONFIG`               | OpenCode config path used by local plugin detection/configuration.                          |
| `OPENCODE_CONFIG_DIR`           | OpenCode config directory used by local plugin detection/configuration.                     |
| `SHELL`                         | Used by install/setup flows that reason about shell profile updates.                        |
| `PATH`                          | Used by install/setup flows and local runtime detection.                                    |
| `WC_NO_UNICODE`                 | Disable Unicode UI symbols when set by the environment.                                     |
| `WEBCOMPUTE_NO_UPDATE_NOTIFIER` | Set to `1` or `true` to suppress CLI update hints and the background update-manifest check. |
| `WEBCOMPUTE_PACKAGES_BASE_URL`  | Override package download base URL for managed local installs.                              |
| `WEBCOMPUTE_INSTALL_BASE_URL`   | Override installer base URL for managed local installs.                                     |

## Local browser-development variables

These are for repo-local browser-server development, not public SDK usage.

| Variable                | Description                                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
| `DISPLAY`               | X display for local browser server development. In containerized dev, use `DISPLAY=:1`.                 |
| `LIBGL_ALWAYS_SOFTWARE` | Force software GL rendering in containers. Use `LIBGL_ALWAYS_SOFTWARE=1` when Chrome crashes due to GL. |

## Release/runtime variables

| Variable                               | Description                                                                                                                                      |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `WEBCOMPUTE_BROWSER_RUNTIME_MATRIX_ID` | Matrix ID for a promoted browser runtime snapshot. Preserve it with deployment records so rollbacks restore the matching snapshot/runtime tuple. |

## Secret handling

Use environment-backed secrets for agent runs:

```bash theme={null}
export VENDOR_PASSWORD="..."
web agent --secret password=VENDOR_PASSWORD "Sign in and collect the current invoice total."
```

Do not place raw API keys, passwords, cookies, proxy URLs, or signed Debug/CDP URLs in prompts.