How to run a coding agent for free with OpenCode 2.0 (parallel agents + Code Mode)

Most coding agents want your credit card before you have typed a single prompt. OpenCode is the opposite. It is MIT licensed, it has crossed 213,000 stars on GitHub, and version 2.0 landed in October 2026 with a real rebuild under it: a shared background service, background subagents that run in parallel, and a new Code Mode that lets the agent chain tools in one sandboxed JavaScript program instead of burning context on round trips.

This is the hands-on version. I will show you how to install v2, point it at a free model (either a built-in free model or a local Ollama model so you pay nothing), run a real task, spawn a read-only reviewer subagent in the background, and wire an MCP server through Code Mode. Then the honest gotchas you will actually hit, because 2.0 is young and it shows.

Prefer the quick version? I walked through the full honest review, the free setup, the parallel agents, and Code Mode in this video:

The mental model first

OpenCode is not a model. It is the harness that drives a model: it reads your codebase, writes and edits files, runs commands, and asks permission before the scary steps. You bring the brain. It supports 75+ providers through the Vercel AI SDK and models.dev, so you can point it at Claude, GPT, Gemini, DeepSeek, or a model running on your own machine.

Version 2.0 changed the shape of the thing. In 1.x, every interface ran its own engine. In 2.0, there is one background service and every interface is just a client of it.

        v1.x                          v2.0
  ┌──────────────┐          ┌──────────┐ ┌──────────┐ ┌──────────┐
  │ terminal+engine│        │ terminal │ │ desktop  │ │ web (pair)│
  └──────────────┘          └────┬─────┘ └────┬─────┘ └────┬─────┘
  ┌──────────────┐               └────────────┼───────────┘
  │ desktop+engine│                            │
  └──────────────┘               ┌─────────────▼─────────────┐
  ┌──────────────┐               │  shared background service │
  │  web+engine  │               │  sessions · config · perms │
  └──────────────┘               │  tool execution · subagents│
    (3 separate brains)          └───────────────────────────┘
                                        (one shared brain)

Open a session in your terminal, then open the same live session in your browser. Same state, same permissions, same running tools. That is the whole point of the rebuild.

Step 1: Install v2

The one-line installer is the safest path on camera and off. v1 and v2 both use the opencode command, so they cannot sit side by side under the default name. Install v2 fresh or upgrade an existing install.

# fresh v2 install
curl -fsSL https://opencode.ai/v2/install | bash

# or via npm
npm install -g @opencode/cli

# or Homebrew
brew install anomalyco/tap/opencode-v2

If you are already on v1, upgrade in place:

opencode upgrade --major

One heads-up: the npm package name shifted between versions (v1 docs used opencode-ai, v2 docs use @opencode/cli). If the npm route gives you the wrong major version, use the curl installer and move on.

Then launch it from inside your project:

cd my-project
opencode

Step 2: Point it at a free model (this is the part people miss)

The agent is free. The model is only free if you make it free. Two paths get you to zero dollars.

Path one, the built-in free models. OpenCode ships a set of hosted free models you can use with no API key at all. Open the model picker inside a session and pick one:

/models

Pick one of the free entries and the whole session costs nothing. (If your org or a plugin hides them, note that the server reads OPENCODE_DISABLE_FREE_MODELS; leave that unset to keep them visible.)

Path two, a local model through Ollama. OpenCode auto-discovers local models from Ollama, LM Studio, and vLLM at their default local addresses. Pull a model and set it in your config:

ollama pull gemma3:4b

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/gemma3:4b"
}

Now nothing leaves your machine and nothing hits a billing meter. For a hosted paid model instead, add your own key and set the model per run:

opencode run --model anthropic/claude-sonnet-4-5 "refactor the auth middleware"

With your own key, the model cost is on you. The agent still costs nothing.

The free and paid landscape at a glance

Step 3: Run a real task

With a model picked, give it something concrete. Type a prompt and watch it inspect the project, decide which files to create, and ask before the important actions.

Build a simple React task manager. Users can add tasks, mark them
complete, delete them, and filter by completed and pending. Keep the
interface clean and responsive.

It plans, writes the files, and stops for permission on the actions that matter. Nothing here is faked UI, it is the real agent editing real files. Review what it produces, because the quality tracks the model you picked and the instructions you gave it, not the OpenCode logo.

Step 4: Spawn a read-only reviewer subagent in the background

This is the 2.0 feature worth the upgrade. The primary agent can hand work to a second agent, even on a different model, and keep going. Shell commands can also run async and report back when they finish. You can delegate a subagent in the prompt, or push a running agent to the background with Ctrl+B.

The safest first use is a read-only reviewer. Tell the primary agent to spawn one and forbid file writes:

Use a reviewer subagent to inspect the task app you just built. Check
for bugs, React best practices, unnecessary re-renders, and
accessibility issues. Do not modify any files. Return a review summary.

The second agent reads, reviews, and hands back findings without touching anything. That is the pattern: split work into smaller specialized agents, keep the destructive ones gated. One honest caveat up front, since I hit it: more agents do not automatically mean better output, and parallel agents on a paid model multiply your bill. Keep an eye on both.

Step 5: Wire an MCP server through Code Mode

Here is the most technical change, and the one that actually saves you money and context. MCP (Model Context Protocol) lets the agent talk to external tools and data: pull docs, call a service, query a database. The old pattern is painful. The agent calls one tool, waits, the result gets stuffed into the model context, it calls the next tool, that result gets stuffed in too, and so on. With many tools, the context fills with data the model never needed to read.

Code Mode flips it. The agent writes one small JavaScript program that calls several tools, maps over the results, and calls the next one, all in a single round trip. The intermediate values stay out of the model context. It runs in a locked-down sandbox with no filesystem, no imports, no timers, no fetch, only your approved catalog tools. It is shipped as @opencode/codemode and surfaced as the execute tool.

  Classic MCP (sequential round trips)
  model → tool A → [result into context]
        → tool B → [result into context]
        → tool C → [result into context]     context bloats

  Code Mode (one sandboxed JS program, one round trip)
  model → execute({ js: "a = toolA(); b = toolB(a); return toolC(b)" })
        → only the final return enters context     context stays clean

Code Mode is on by default for MCP servers. You opt a server in or out with the codemode flag:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "codemode": true
    }
  }
}

Set codemode to false when you want the raw tools exposed to the model instead. The savings are real. The documented drop in testing was about 69%, from 177,444 tokens down to 54,181 on a tool-heavy run. You will see a third-party project throwing around a 98% number. That figure belongs to a separate tool, not OpenCode. Do not plan around it.

Step 6: Open the same session in the browser

To get the shared-service payoff, open the web client:

opencode pair

It prints a connection link and credentials. The link works once and expires in about five minutes, so use it promptly. Now your terminal session and your browser view the same live state.

OpenCode 2.0 vs Claude Code vs Codex

I want to be precise here. There is no independent benchmark proving OpenCode writes better code than Claude Code. Its edge is flexibility and openness, not a proven quality win. Anyone telling you it beats Claude Code on output is guessing.

When to use OpenCode 2.0

1. You want a serious coding agent for zero dollars. Built-in free models or a local Ollama model gets you a capable agent with no API bill at all.
2. You care about model freedom. 75+ providers and local models mean you are never locked to one vendor, and you can switch per task.
3. You want one session across surfaces. The shared service lets the terminal, desktop, and browser view the same live work.
4. You lean on MCP tools heavily. Code Mode is a real context and cost win when an agent chains many external tools.

When NOT to use it

1. You need rock-solid for production today. 2.0 is young, and the background-subagent lifecycle is still being fixed. For a critical project this week, a mature tool is the safer pick.
2. You are chasing the best possible code quality on a hard task. Output tracks the model, not the harness. On a free local model, expect free-local-model results.
3. You cannot spend time on setup. Models, permissions, and custom agents all need configuring. It is not a one-click experience.
4. You are on the free tier and want custom subagents. Custom subagents are rejected on the free tier (first-party issue #54111), so budget for that.

The gotchas I hit, from real community reports

Background subagents report "done" at spawn. This is the roughest early-2.0 edge. When a subagent spawns with background: true, the chip can resolve instantly with no spinner and nothing in the subagents panel, while the child session is still working. It is documented across multiple trackers (zeronsh/zeron #845, first-party anomalyco/opencode #48826 for results never collected, and #31789 for a re-dispatch loop). Treat a "done" chip with suspicion until the output actually lands.

The always-on service is memory heavy. The shared service is the headline feature and also the headline complaint. Hacker News threads and first-party issues report high idle RAM and CPU: an idle serve burning 20 to 45% CPU in bursts (#42299), 2GB on launch, and in extreme long-session cases far worse. If you are on a small VPS or a laptop with tight RAM, watch it, and stop the service when you are not using it.

The SDK and plugin API are young and churny. 2.0 ships a rebuilt server API, an SDK (@opencode/client to connect to a running service, @opencode/sdk to embed it as a library), and a new plugin system. All of it is new. Pin your versions and expect breaking changes between releases. Some v1 plugins need changes to work on v2.

Parallel agents multiply cost. Obvious once you say it, easy to forget in the moment. Two background agents on a paid model is two bills running at once.

A safer way to evaluate it

1. Install into a throwaway project or a git worktree, not your main repo.
2. Start on a built-in free model or local Ollama so the first session costs nothing.
3. Give it a read-only task first (review, summarize, explain) before anything that writes files.
4. Keep the reviewer subagent set to no file writes until you trust it.
5. Read the diff yourself and run the tests yourself. Do not trust a "done" chip.
6. Watch memory and CPU on your machine for the first few sessions, and stop the service when idle.
7. Pin SDK and plugin versions and expect to re-pin on upgrade.

Official resources

• Repo: https://github.com/anomalyco/opencode
• v2 docs: https://opencode.ai/v2/docs
• v2 models and local setup: https://opencode.ai/v2/docs/models/
• v2 tools and Code Mode: https://opencode.ai/v2/docs/tools/
• Migrate from v1: https://opencode.ai/v2/docs/migrate-v1/
• Makers' 2.0 note (Anomaly): https://anoma.ly/notes/opencode-2-0/

That is the whole setup: free model, real task, a background reviewer, and an MCP server running through Code Mode, with the rough edges flagged so they do not surprise you.

Have you run OpenCode 2.0 on a real project yet? Tell me in the comments whether the shared service is worth the memory it eats, and whether you caught the subagent "done" bug too. If you want quick, honest breakdowns of each big AI tool launch, follow GoVenture on YouTube for the next one.