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

> AI Release · @ai_release1 · https://ai-release.org/guides/kak-ustanovit-i-nastroit-opencode-v2-brauzer-dlya-agent_en.html

## TL;DR

- **Time to complete:** 25–35 minutes
- **Difficulty:** Intermediate
- **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.

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](https://ai-release.org/guides/img/kak-ustanovit-i-nastroit-opencode-v2-brauzer-dlya-agent-en-1.jpg?v=1794818674)


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:

```bash
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](https://ai-release.org/guides/img/kak-ustanovit-i-nastroit-opencode-v2-brauzer-dlya-agent-en-2.jpg?v=1794818677)


**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.

```bash
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:

```bash
opencode auth login
```

```json
{
  "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:

```bash
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](https://ai-release.org/guides/kak-ustanovit-i-nastroit-oh-my-pi-omp-konsolnyy-ii-agen.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_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`:

```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](https://ai-release.org/guides/img/kak-ustanovit-i-nastroit-opencode-v2-brauzer-dlya-agent-en-3.jpg?v=1794818682)


**What to do:** run one short task that exercises all three features, then lock the spend levers.

```bash
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:

- [ ] The command completes and prints a numbered list of three differences.
- [ ] The output references actual page content (a heading or price string), not a guess — proof the browser read the DOM.
- [ ] No more than two subagent sessions were active simultaneously.
- [ ] A second run of the same prompt reuses the same model ids (no silent fallback to a default).
- [ ] Your provider dashboard shows the request count you expect, not a multiple of it.

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](https://ai-release.org/guides/kak-nastroit-limity-rashodov-i-byudzhety-dlya-ii-agento.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

**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**

- Error: `Error: Unexpected token } in JSON at position <N>` (the number varies)
- Cause: a trailing comma after the last key in `opencode.json` — JSON does not allow it, even though JavaScript does.
- Solution: validate and fix:

```bash
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**

- Error: `model not found: <provider>/<model-id>`
- Cause: the id in `model` does not match what the provider exposes — usually a stale or misspelled variant suffix.
- Solution: list the ids your credentials can actually reach (check the documentation for the exact listing command in your build), copy one verbatim into `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**

- Error: `Subagent aborted: rate limit exceeded (429)` in the session log
- Cause: `max_parallel` is above your provider's requests-per-minute tier, so the second and third subagent calls are rejected.
- Solution: drop to `"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.

## 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](https://ai-release.org/guides/kak-ustanovit-ai-manus-i-zapustit-pervogo-ii-agenta-pos.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide) 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.
