Environment Variables

Variable	Description	Default
`CDP_URL`	CDP endpoint to attach to	`http://127.0.0.1:9222`
`WEBRAIN_PROXIES`	Proxy rotation pool — comma/newline-separated proxy URLs, round-robin in list order (first entry used first), with a walled exit resting 120 s before it is retried. Used by the HTTP engines (`webrain_serp`, `webrain_scrape`) and baked into the google/brave guest-Chrome launch. Process-global — an explicit per-call `proxy` overrides it and never rotates	unset (no pool)
`WEBRAIN_HTTP_CACHE`	Set `0`/`off`/`false`/`no` to disable the HTTP revalidation cache (conditional GETs on repeat fetches)	on
`WEBRAIN_HTTP_CACHE_DIR`	Dir holding the HTTP cache metadata file	platform cache dir (`%LOCALAPPDATA%\webrain`, `~/.cache/webrain`)
`WEBRAIN_DOWNLOAD_MAX_BYTES`	Per-file size cap in bytes for the `webrain_download` http engine	`536870912` (512 MiB)
`WEBRAIN_FETCH_TIMEOUT_SECS`	Per-attempt HTTP timeout for engine/package downloads — raise it on a slow link so a slow install is slow, not failed	`300`
`WEBRAIN_CHROME`	Explicit Chrome binary path	auto-discovered
`WEBRAIN_BROWSERS_DIR`	Engine cache dir (Chrome for Testing, Obscura)	`%LOCALAPPDATA%\webrain\browsers` / `~/.cache/webrain/browsers`
`WEBRAIN_LIGHTPANDA` / `WEBRAIN_OBSCURA`	Explicit lightpanda/obscura binary paths	auto-discovered
`WEBRAIN_PROFILES_DIR`	Per-account browser profile root	`%APPDATA%\webrain\profiles` / XDG data dir, i.e. `~/.local/share/webrain/profiles`
`WEBRAIN_MAX_TABS`	Cap on concurrent tabs an engine may open — lower it on a small box where a wide `webrain_batch` would thrash memory	engine default
`WEBRAIN_VAULT_DIR`	Encrypted credential vault dir	`%APPDATA%\webrain` / `~/.config/webrain`
`WEBRAIN_USER` / `WEBRAIN_PASS`	Login fallback credentials (env channel)	—
`GROQ_API_KEY` / `OPENAI_API_KEY` / `FIREWORKS_API_KEY`	Cloud STT (transcript) keys, tried GROQ → OPENAI → FIREWORKS. The vision `ask` chain is separate and uses all three too — see Vision `ask` chain	—
`OPENROUTER_API_KEY`	Vision `ask` chain, first hop	—
`ANTHROPIC_API_KEY` / `CLAUDE_API_KEY`	Vision `ask` chain, hop 3 (Claude). Either name works	—
`GEMINI_API_KEY` / `GOOGLE_API_KEY`	Vision `ask` chain, hop 4 (Gemini). Either name works	—
`DASHSCOPE_API_KEY` / `QWEN_API_KEY`	Vision `ask` chain, hop 6 (Qwen / DashScope). Either name works	—
`SERPAPI_API_KEY`	serpapi.com paid Google SERP provider — used by `webrain_serp` when `limit > 10`	—
`BRAVE_API_KEY`	Brave Search API (`api.search.brave.com`, 20/page) — makes `engine=brave` work without a browser, and `auto` uses it for `limit > 20` before any browser render	—
`WEBRAIN_SKILLS_DIR`	Directory of operator skill files readable via `webrain_guide(topic="skill:<name>")` — ship house rules to the agent without recompiling. Unset means `<engine cache>/skills`, which `webrain install skills` fills and `webrain skills add <url>` extends; an empty directory serves nothing	— (empty)
`WEBRAIN_NO_STEALTH`	Set `1` to skip the injected stealth JS + UA override (e.g. the `webrain serp` google flow). `serp` sets it for itself — if it leaks into the shell that starts `mcp`, the server boots with all stealth off and every later result is measured against a different identity	off
`WEBRAIN_STEALTH_NOISE`	Set `0` to disable the canvas/audio/`Object.defineProperty` fingerprint-noise block. This is the fix when a page renders but never mounts. Verified on `ab.gr/storelocator` (real Chrome): the NOISE block made Next.js abort with `Cannot read properties of undefined (reading 'getInitialProps')`, and the same browser mounted cleanly with it off. Read at attach — restart the server, then open a fresh tab; injected scripts live for the tab’s lifetime, so re-navigating the same tab keeps the old one and the change looks ignored	on
`WEBRAIN_STT_MODEL`	Cloud STT model override (e.g. `whisper-large-v3`)	provider default
`WEBRAIN_WHISPER_BIN` / `WEBRAIN_WHISPER_MODEL`	Local whisper-cli binary / GGUF model paths	bundled cache
`WEBRAIN_VISION_MODEL`	Which installed local vision model to load (`qwen3-vl-2b`, `qwen3-vl-2b-q6k`, `qwen35-9b-q4km`/`q5km`/`q6k`/`q8`). Unset resolves to the default id, then to whatever is installed, so a single-model cache keeps working	`qwen3-vl-2b`
`WEBRAIN_LLAMA_SERVER`	Path to a different `llama-server` binary — drop in a CUDA/Vulkan build and GPU offload engages on its own	bundled CPU build
`WEBRAIN_VISION_GPU`	`1` forces `-ngl 99` layer offload, `0` forces CPU. Otherwise offload is enabled only when a GPU backend library (`ggml-cuda`, `ggml-vulkan`, `ggml-metal`, `ggml-hip`, `ggml-sycl`) sits beside the binary — `-ngl` on a CPU-only build is silently ignored, so the machine’s GPU is never trusted over the build’s	auto
`EMBED_URL` / `EMBED_MODEL` / `EMBED_API_KEY`	OpenAI-compatible `/v1/embeddings` endpoint + model + Bearer token for `webrain_vision` `op=index` / `retrieve` (any compatible server: OpenAI, Ollama, TEI, local vLLM)	`api.openai.com/v1/embeddings` + `text-embedding-3-small`
`EMBED_FALLBACK_URL` / `EMBED_FALLBACK_MODEL` / `EMBED_FALLBACK_API_KEY`	Secondary embeddings endpoint tried automatically when the primary `EMBED_*` call fails	`http://127.0.0.1:8000/v1/embeddings` + `Qwen/Qwen3-VL-Embedding-2B`
`WEBRAIN_HTTP_ADDR`	Bind address for `webrain mcp --http`	`127.0.0.1:<port>` (loopback only)
`WEBRAIN_HTTP_TOKEN`	Bearer token for the HTTP transport, compared in constant time. Required on a non-loopback bind	unset (open on loopback)
`WEBRAIN_ALLOW_UNAUTHENTICATED`	Set `1` to permit a non-loopback HTTP bind with no token — otherwise startup refuses	off
`WEBRAIN_NO_STATE`	Set `1` to refuse the vault / launch / login / session tools and clamp fan-out (shared-instance mode)	off
`RUST_LOG`	Log verbosity (`webrain=info,tungstenite=warn`)	as above

Vision `ask` chain

webrain_vision op=ask (and watch --vision) tries every provider whose key is set, in this order, then the bundled local model. All cloud hops are the same OpenAI-compatible POST /chat/completions call with base64 image_url content, so one key is enough and an unset key merely drops its hop. A failing hop falls through to the next; the error reports every hop that failed, not just the last.

#	Key (first non-empty wins)	Endpoint	Model
1	`OPENROUTER_API_KEY`	`openrouter.ai/api/v1/chat/completions`	`qwen/qwen3.6-27b`
2	`OPENAI_API_KEY`	`api.openai.com/v1/chat/completions`	`gpt-4o-mini`
3	`ANTHROPIC_API_KEY` / `CLAUDE_API_KEY`	`api.anthropic.com/v1/chat/completions`	`claude-sonnet-4-5`
4	`GEMINI_API_KEY` / `GOOGLE_API_KEY`	`generativelanguage.googleapis.com/v1beta/openai/chat/completions`	`gemini-2.5-flash`
5	`FIREWORKS_API_KEY`	`api.fireworks.ai/inference/v1/chat/completions`	`accounts/fireworks/models/qwen2.5-vl-72b-instruct`
6	`DASHSCOPE_API_KEY` / `QWEN_API_KEY`	`dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions`	`qwen3-vl-plus`
7	`GROQ_API_KEY`	`api.groq.com/openai/v1/chat/completions`	`qwen/qwen3.8-27b`
8	—	bundled `llama-server`	`qwen3-vl-2b` (or whatever `webrain install vision` installed)

Notes that cost real time to learn:

Anthropic and Gemini are reached through their OpenAI-compatibility layer, so the key goes in the normal Authorization: Bearer header — no x-api-key / ?key= special-casing, and no second request builder.
The alias pairs exist because each vendor documents its variable differently (CLAUDE_API_KEY, GOOGLE_API_KEY, QWEN_API_KEY are all accepted).
No key at all is not a silent failure: the error names every variable to set and points at webrain install vision for the offline fallback.
DeepSeek is deliberately absent — its hosted API rejects image_url content.
Groq’s id is qwen/qwen3.8-27b, not OpenRouter’s qwen/qwen3.6-27b; Groq never carried the 3.6 id, so sharing it made that hop a permanent 404.

Local AI (watch & vision)

webrain_watch transcribes locally via bundled whisper-cli + a GGUF model, and vision:true describes frames via a vision LLM — local Qwen3-VL-2B (bundled llama-server, webrain install vision) when no cloud key is set.

Install	What it bundles
`webrain install watch`	ffmpeg+ffprobe, yt-dlp, whisper-cli + a GGUF model
`webrain install whisper`	a whisper GGUF model (`--model small.en`)
`webrain install vision`	llama-server (latest CPU build) + one vision model from the catalog — default `qwen3-vl-2b`, or `--model <id>`
`webrain install vision --model <id> --model-update`	re-checks that model’s files against Hugging Face (a changed upstream size re-downloads)
`webrain uninstall vision --model <id>` / `--all`	removes one model dir, or the whole `vision/` cache

Models live in vision/<id>/ with their own mmproj; the ids, sizes and RAM/VRAM needs are listed in the installation guide.

Chat (Copilot BYOK)

webrain chat reuses the same key names as the vision chain above — set one variable and both work — but resolves them for a chat model instead of a vision model. First match wins: flags → WEBRAIN_CHAT_* → the ambient chain.

Variable	Description	Default
`WEBRAIN_CHAT_PROVIDER`	row to use: `openrouter`, `openai`, `anthropic`/`claude`, `gemini`/`google`, `fireworks`, `dashscope`/`qwen`, `groq`, `deepseek`	ambient order
`WEBRAIN_CHAT_MODEL`	override the row’s default model id	row default
`WEBRAIN_CHAT_BASE_URL`	override the row’s base url. Any OpenAI-compatible endpoint; a key is then optional, which is how a local Ollama/vLLM server is reached	row default
`WEBRAIN_CHAT_API_KEY`	the key itself, for one variable instead of a vendor-named one	—
`COPILOT_CLI_PATH`	use a Copilot runtime you already have instead of the bundled one	bundled
`COPILOT_CLI_EXTRACT_DIR`	where the bundled runtime is unpacked on first use	platform cache
`BUNDLED_CLI_CACHE_DIR`	build-time cache of the runtime archives (CI)	—
`WEBRAIN_CHAT_DEBUG`	mirror every raw session event to stderr — the only way to see the provider’s own error when a turn returns no answer	off
`WEBRAIN_CHAT_HOME`	the `COPILOT_HOME` the chat runtime is given: sessions, auth and config live here, and `~/.copilot` is deliberately not used (inheriting it loaded ~480 unrelated tools)	`webrain-copilot-home` under the temp dir

The ambient chain, in order, with each row’s base url and default model:

Key (aliases)	`base_url`	default model
`OPENROUTER_API_KEY`	`https://openrouter.ai/api/v1`	`anthropic/claude-sonnet-4.5`
`OPENAI_API_KEY`	`https://api.openai.com/v1`	`gpt-5`
`ANTHROPIC_API_KEY` / `CLAUDE_API_KEY`	`https://api.anthropic.com/v1`	`claude-sonnet-4-5`
`GEMINI_API_KEY` / `GOOGLE_API_KEY`	`https://generativelanguage.googleapis.com/v1beta/openai`	`gemini-2.5-pro`
`FIREWORKS_API_KEY`	`https://api.fireworks.ai/inference/v1`	`accounts/fireworks/models/qwen3-235b-a22b`
`DASHSCOPE_API_KEY` / `QWEN_API_KEY`	`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`	`qwen3-max`
`GROQ_API_KEY`	`https://api.groq.com/openai/v1`	`qwen/qwen3.8-27b`

A named provider uses only its own variables: --provider groq with just OPENAI_API_KEY set is an error rather than a key sent to the wrong vendor. webrain chat --print-config resolves the whole chain and prints it with the key replaced by <redacted> — offline, no runtime needed. See the chat guide.

Discovery order

Binaries are discovered automatically on every OS: env override → PATH → ~/.lightpanda, ~/.obscura, ~/.local/bin → the webrain engine cache.

Getting Started

MCP Clients

Concepts

Agent

Guides

Comparisons

Reference

Project

Environment Variables

Environment Variables

Vision `ask` chain

Local AI (watch & vision)

Chat (Copilot BYOK)

Discovery order

​Environment Variables

​Vision ask chain

​Local AI (watch & vision)

​Chat (Copilot BYOK)

​Discovery order

Environment Variables

Vision `ask` chain

Local AI (watch & vision)

Chat (Copilot BYOK)

Discovery order