← All guides AI Release
RU Subscribe to @ai_release1

How to Install and Configure Opencode v2: Agent Browser, Background Subagents and Model Cost Control

Updated: 16.11.2026 · AI Release · @ai_release1
How to Install and Configure Opencode v2: Agent Browser, Background Subagents and Model Cost Control

TL;DR

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.

Requirements and setup

Illustration: Requirements and setup
Illustration: Requirements and setup

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.

ComponentWhat it adds to the billDefault risk if left unconfigured
Main agent sessionOne prompt per turn, growing with contextLong browser sessions inflate every later turn
Background subagentsOne full conversation per subagentN subagents = N parallel spend streams
Agent browserPage text, snapshots, screenshots in contextWhole-site crawling when you only needed one page
Model routingCheap model for small steps, strong model for planningStrong 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.

Step 1. Install Opencode v2 and write the base config

Illustration: Step 1. Install Opencode v2 and write the base config
Illustration: Step 1. Install Opencode v2 and write the base config

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.

Step 2. Enable the agent browser and background subagents

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.

Step 3. Verify the pipeline end to end and cap spend

Illustration: Step 3. Verify the pipeline end to end and cap spend
Illustration: Step 3. Verify the pipeline end to end and cap spend

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:

LeverWhat it changesWhere 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 budgetWhen the agent stops on its ownsession limits — check the documentation for the exact key
Provider-side hard capThe ceiling nothing can exceedprovider 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.

Troubleshooting

Problem. Opencode refuses to start after you add the browser block

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

Problem. Subagents start but never return results

Summary and next steps

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.

FAQ

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.

🤖 AI summary

AI Release Knowledge Layer
Machine-readable description · Version 1.0

Status: practical guide. Some statements come from vendors; verify in your environment.

1. Summary

Time to complete: 25–35 minutes Difficulty: Intermediate

Inside: direct answers, key facts, entities, context, reliability, unknowns and sources.

Machine data: Citation Map JSON · JSON-LD · Semantic Embeddings — separate stage.

Full Knowledge Layer: sections 2–8

2. Direct answers

How to do it?
Step 1. Install Opencode v2 and write the base config → Step 2. Enable the agent browser and background subagents → Step 3. Verify the pipeline end to end and cap spend → details (AR-GUIDE-KAKUSTANOV-004)
Which topics does it cover?
opencode установка, opencode v2 настройка, opencode субагенты, браузер для ии-агента, стоимость токенов opencode → details (AR-GUIDE-KAKUSTANOV-002)
What are the key points?
Time to complete: 25–35 minutes Difficulty: Intermediate → details (AR-GUIDE-KAKUSTANOV-007)

3. Key facts

  1. Time to complete: 25–35 minutes — evidence; status: заявление источника.
  2. Difficulty: Intermediate — evidence; status: заявление источника.
  3. You will need: macOS, Linux, or Windows with WSL2; Node.js LTS if you install through npm; git; one model-provider API key (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. — evidence; status: заявление источника.

4. Entities

EntityTypeRole
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 или разделах гайда

5. Context

  • Guide — describes → How to Install and Configure Opencode v2: Agent Browser, Background Subagents and Model Cost Control (AR-GUIDE-KAKUSTANOV-001).
  • Guide — includes step → Step 1. Install Opencode v2 and write the base config (AR-GUIDE-KAKUSTANOV-001).

6. Reliability

Confirmed

No independent confirmation is provided; source claims and editorial conclusions are separated below.

Source claims

  • Product features, versions, prices and limits come from vendors and the guide.
  • Commands and steps are recommendations, not guaranteed results.

AI Release analysis

  • Structure, comparison and selection criteria are editorial.
  • The guide does not replace an independent audit or legal advice.

7. Unknowns

  • Current versions, prices and limits.
  • Independent benchmarks and quality checks.
  • Terms of use and data policy.

8. Sources

SourceTypeRole
No external links——

Cite as: AI Release. Как установить и настроить Opencode v2: браузер для агента, фоновые субагенты и контроль стоимости моделей. ai-release.org.