ANTHROPIC_API_KEY or OPENAI_API_KEY) exported in your shell; a project folder with git init already run; about 500 MB of free disk space.The result: a working Opencode v2 session where the agent can drive a browser, spawn background subagents for parallel work, and where both the browser and the subagents are bounded by an explicit model-and-cost policy instead of running on defaults.

Opencode is a terminal agent: you type a task, it plans, calls tools (file edits, shell commands, a browser), and writes the result back into your project. Three parts of v2 change how much it can do *and* how much it can spend, so understand them before touching config:
1. Agent browser — a browser instance the agent controls itself, so it reads pages and DOM state instead of you pasting HTML into the chat. Cost driver: every page it visits adds context to the model prompt.
2. Background subagents — child agent sessions that run in parallel on separate sub-tasks while the main session continues. Cost driver: each subagent is a separate billed conversation.
3. Model cost control — routing cheap work to a cheaper model and bounding the two items above. Cost driver: without it, the biggest model answers every trivial step.
| Component | What it adds to the bill | Default risk if left unconfigured |
|---|---|---|
| Main agent session | One prompt per turn, growing with context | Long browser sessions inflate every later turn |
| Background subagents | One full conversation per subagent | N subagents = N parallel spend streams |
| Agent browser | Page text, snapshots, screenshots in context | Whole-site crawling when you only needed one page |
| Model routing | Cheap model for small steps, strong model for planning | Strong model used for formatting and summaries |
Check the baseline first:
node --version && git --version
echo "key set: ${ANTHROPIC_API_KEY:0:8}..."
Expected output: a Node version line, a git version line, and key set: sk-ant-... (or the prefix of your provider's key). If the key line prints only key set: ..., the variable is empty — export it in the same shell before continuing.
Example: for a documentation-scraping task, the browser only needs docs.example.com, and two subagents are enough. That is the configuration you will build in Step 2.

What to do: install the CLI, authenticate against a provider, and create a project-level opencode.json that pins which model does the main work and which model handles small steps.
npm install -g opencode-ai
opencode --version
If npm returns a 404 for that package name in your environment, use the official install command from the Opencode docs (check the documentation) — the version check below is identical either way.
Why: pinning two models up front is the cheapest cost control you have. Everything the main agent does runs on model; titles, summaries, and classification run on small_model. Doing this before your first prompt means no accidental spend on the large model for trivia.
Authenticate, then create the project config:
opencode auth login
{
"model": "<provider>/<strong-model-id>",
"small_model": "<provider>/<cheap-model-id>"
}
Save it as opencode.json in the repository root (project scope) or at ~/.config/opencode/opencode.json (global). The project file wins, which is what you want: a scraping repo and a refactoring repo have different budgets.
How to check: run opencode in the project root and confirm the startup panel shows your selected model id, not an auto-detected default. Then send one throwaway prompt:
opencode run "Reply with the model id you are running on."
Expected output: the <provider>/<strong-model-id> string you wrote. If it prints a different model, your project config was not picked up — confirm you are in the directory that contains opencode.json, and that the file parses (python3 -m json.tool opencode.json).
If you want a second reference point for a terminal agent with a different permission model, the Oh-My-Pi setup guide walks through the same install/authenticate/first-run sequence.
What to do: turn on the browser and subagents, then bound both — allowed domains for the browser, a hard parallelism cap for subagents. Extend the same opencode.json:
{
"model": "<provider>/<strong-model-id>",
"small_model": "<provider>/<cheap-model-id>",
"browser": {
"enabled": true,
"headless": true,
"allowed_domains": ["docs.example.com", "localhost"]
},
"subagents": {
"enabled": true,
"max_parallel": 2
}
}
The block names above follow the v2 settings layout. If Opencode prints an "unknown config key" warning on startup, check the documentation for the exact spelling used by your build — the values (true, 2, the domain list) stay the same regardless.
Why: allowed_domains is the difference between "read this one page" and "wander the internet on your credit card". max_parallel: 2 means at most two extra conversations are billed at once; without a cap, a task like "check these twelve links" can fan out to twelve.
Also set the permission policy so the agent asks before it navigates somewhere new or writes files outside the repo — an approval prompt is cheaper than a rolled-back commit.
Example: prompt Open http://localhost:3000/pricing, extract the plan table, then have two subagents summarise /docs/auth and /docs/api in parallel. With the config above the agent stays on localhost and docs.example.com, and the two summaries run as exactly two subagent sessions.
How to check: run the prompt and watch the status area of the TUI. You should see a browser session line once the page loads, and subagent entries appearing — of the form subagent started: <task> — with no more than two active at a time. Cancel with Esc if the browser tries to leave the allowed list; that means the domain list is missing an entry, not that the browser is broken.

What to do: run one short task that exercises all three features, then lock the spend levers.
opencode run "Read README.md, open http://localhost:3000, and list 3 differences between them."
Why: a combined task proves the three pieces work *together* — a browser that works alone but blocks subagents, or a subagent cap that silently disables the browser, only shows up in a mixed run.
How to check — walk this checklist and confirm each line:
Then apply the spend levers:
| Lever | What it changes | Where to set it |
|---|---|---|
| `model` / `small_model` | Which model answers planning vs. trivia | `opencode.json` |
| `subagents.max_parallel` | How many conversations bill at once | `opencode.json` |
| `browser.allowed_domains` | How much page text enters context | `opencode.json` |
| Per-session step/turn budget | When the agent stops on its own | session limits — check the documentation for the exact key |
| Provider-side hard cap | The ceiling nothing can exceed | provider billing console |
Set the provider-side cap last and treat it as the backstop: local config stops the agent, the billing cap stops the account. For the account-level side, including how to size a monthly ceiling for an agent that runs unattended, see How to Set Spending Limits and Budgets for AI Agents.
Example: with max_parallel: 2 and a cheap small_model, a twelve-link audit runs as six sequential batches of two instead of twelve parallel sessions — slower by a minute, a fraction of the cost.
Problem. Opencode refuses to start after you add the browser block
Error: Unexpected token } in JSON at position <N> (the number varies)opencode.json — JSON does not allow it, even though JavaScript does.python3 -m json.tool opencode.json > /dev/null && echo "JSON OK"
The command prints the parse error with the line number if the file is still invalid, and JSON OK when it is clean. Re-run opencode afterwards.
Problem. The first prompt fails immediately with a model error
model not found: <provider>/<model-id>model does not match what the provider exposes — usually a stale or misspelled variant suffix.model, and re-run opencode run "Reply with the model id you are running on." until it echoes the id back.Problem. Subagents start but never return results
Subagent aborted: rate limit exceeded (429) in the session logmax_parallel is above your provider's requests-per-minute tier, so the second and third subagent calls are rejected."max_parallel": 1, confirm the single subagent completes, then raise it one step at a time. If 1 still returns 429, the limit is on your API key tier, not on Opencode.You now have Opencode v2 installed with a pinned model pair, a domain-limited agent browser, a capped number of background subagents, and a provider-side ceiling behind all of it. Next, add a per-session step budget so long browser sessions stop on their own, and compare the permission model against the AI Manus first-agent walkthrough before you let either agent run unattended.
Does the agent browser replace my own browser session?
No. It is a separate, usually headless instance that the agent controls, and it is restricted to the domains in allowed_domains. Your cookies and logged-in tabs are not shared with it.
How many background subagents should I allow?
Start at 2. Raise it only after confirming your provider tier tolerates the parallel request rate — the 429 error in Troubleshooting is the signal that you went too far.
Why route small tasks to a different model?
Because formatting, titling, and classification do not need the strongest model, and the small_model key sends exactly those calls to a cheaper one. The main model still handles planning and code edits.
Does a browser session raise cost even when the answer looks short?
Yes. Page text and snapshots enter the conversation context, so every later turn in that session carries them. Narrowing allowed_domains and starting a fresh session per page is the cheapest fix.
Status: practical guide. Some statements come from vendors; verify in your environment.
Time to complete: 25–35 minutes Difficulty: Intermediate
Machine data: Citation Map JSON · JSON-LD · Semantic Embeddings — separate stage.
| Entity | Type | Role |
|---|---|---|
| opencode установка | тема/инструмент | упоминается в заголовке, TL;DR или разделах гайда |
| opencode v2 настройка | продукт/модель | упоминается в заголовке, TL;DR или разделах гайда |
| opencode субагенты | тема/инструмент | упоминается в заголовке, TL;DR или разделах гайда |
| браузер для ии-агента | тема/инструмент | упоминается в заголовке, TL;DR или разделах гайда |
| стоимость токенов opencode | тема/инструмент | упоминается в заголовке, TL;DR или разделах гайда |
| Windows | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| Linux | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| macOS | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| Node.js | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| npm | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
No independent confirmation is provided; source claims and editorial conclusions are separated below.
| Source | Type | Role |
|---|---|---|
| No external links | — | — |
Cite as: AI Release. Как установить и настроить Opencode v2: браузер для агента, фоновые субагенты и контроль стоимости моделей. ai-release.org.