Running Many OpenCode Sessions at Once

One agent working on one task is a straightforward thing to supervise. Several agents working at once is a different job, and it is closer to operations than to editing. OpenCode gives you the parts for that job, and it does not hand you a finished control room.

The Decision This Page Settles

This page settles how to run more than one OpenCode session at a time without the runs colliding, and when a fleet is worth the extra supervision. You will end with a session layout, an isolation boundary you chose deliberately, and a rule for when to stop adding sessions.

Why One Session Stops Being Enough

The pressure to run several sessions usually arrives for one of a few reasons, and they are worth separating because they call for different setups.

• Waiting: a long refactor blocks you while a small fix sits untouched.
• Independence: two tasks touch different parts of the repository.
• Comparison: you want the same task attempted by two different models.
• Repetition: the same mechanical change applies across many packages.
• Scheduling: a job should run without a person sitting in front of it.

Only the last two genuinely want automation. The first three want a second window and a clear rule about which files each session may touch. Reaching for orchestration when the real need is a second terminal adds machinery you then have to maintain.

Use the Client and Server Split

OpenCode runs as a client talking to a server rather than as a single terminal program. That split is what makes a fleet possible at all, because the session lives with the server and the client is just a view onto it. A plain opencode run starts both, so persistence depends on a server you keep alive.

Three things follow from that, and each one is a capability you can use or ignore:

• Several sessions can run against one project at the same time.
• A client can attach to a running server from another machine, once you have secured it.
• A session remains available after a client disconnects while the OpenCode server keeps running.

Keep one project per server where you can. Mixing several repositories behind one server makes it harder to reason about which permission rules and which environment a given session inherited.

Give Each Session Its Own Worktree

This is the step most fleets skip, and it is the one that decides whether parallel work is useful or a merge problem. A git worktree is a second checkout of the same repository in its own folder, sharing one history.

Two sessions editing the same working tree will overwrite each other's changes without either one noticing, because neither reads the other's context. Separate worktrees turn that silent conflict into an ordinary merge you handle at the end.

Isolation	Cost	Use When
One working tree	None	One session only
Git worktrees	Disk, one branch each	Parallel edits, one repo
Separate clones	Full copy each	Different dependencies
Containers	Setup and images	Untrusted commands

Name the branch after the task, not after the session number. When you come back to four running jobs an hour later, the branch name is the only label that still tells you what the agent was asked to do.

Drive a Session from a Second Device

Because the client attaches to a server, you can start a long job at your desk and check it from a laptop or a phone. That is genuinely useful for jobs measured in tens of minutes.

Get the security order right, because the default is not what people assume. The server binds to 127.0.0.1 and ships with no authentication at all, so anything that can reach it can run commands on that host.

OpenCode's documented protection is OPENCODE_SERVER_PASSWORD, which turns on HTTP basic auth for opencode serve and opencode web. The username defaults to opencode unless OPENCODE_SERVER_USERNAME overrides it. That is the exact invocation its server page shows:

OPENCODE_SERVER_PASSWORD=your-password opencode serve

The variable is the only documented switch for this. There is no password flag on opencode serve, and the server still listens on 127.0.0.1 at port 4096 until --hostname or --port changes it.

Prefer SSH port forwarding for cross-machine access, so the listener stays on localhost and your existing SSH keys do the authenticating. Exposing the server on a network is the riskier path: basic auth sends the password and every prompt unencrypted, so it also needs TLS in front of it, such as a reverse proxy, with the password set before anything else.

Forwarding is two commands on the second device, one per terminal. The first command is standard OpenSSH port forwarding, not an OpenCode feature; the second attaches a client to the forwarded port rather than to a network address:

ssh -N -L 4096:127.0.0.1:4096 you@your-dev-machine
opencode attach http://127.0.0.1:4096 --password your-password

Nothing on the dev machine changed for that to work, which is the point. The server kept its localhost bind, and SSH carried the encryption that basic auth does not. The --password flag is how attach presents the server's basic-auth credential from the second device, since the environment variable you set in the server's terminal does not exist there; it is only needed when the password is set.

A second device is for watching and answering approval prompts. Writing a fresh multi-file task on a phone keyboard is how vague prompts get sent, and a vague prompt costs more to review than it saved to type.

Script the Fleet Headless

The repetition case is the one that deserves a script. When the same mechanical change applies across many packages, a loop that runs OpenCode once per package is more reliable than one session asked to remember twelve directories.

The command for that is opencode run, which OpenCode documents as its non-interactive mode: it takes the prompt as an argument and exits when the run finishes.

opencode run "Update this package's lint config to match the repo root."

Four of its flags matter once a script owns the run. --agent picks which agent handles it, --model pins the provider and model, --format json gives output a script can parse, and --auto approves permission prompts so nothing waits for a human who is not there.

Read that last one carefully. With --auto set there is no approval step left, so your permission rules are the only boundary the run has.

Three rules keep a scripted fleet from becoming a liability:

1. Run each unit against its own branch, so a bad run is one branch to delete.
2. Set permissions explicitly for the script's user, never inheriting your interactive setup.
3. Fail loudly on the first unit before letting the loop touch the rest.

A loop carrying the third rule is three lines of shell:

for pkg in packages/*/; do
  opencode run --agent build "Update the lint config in $pkg to match the repo root." || exit 1
done

That stops at the first failure instead of working through the rest of the directory. It does not give you the first rule, and it is worth being clear about why: every run lands in the same working tree, so uncommitted changes from one package are still sitting there when the next one starts.

Branch-per-unit therefore needs a commit, a stash, or a separate checkout between runs. That is a longer script than this page should pretend, and it is the point at which a repetitive job stops being three lines of shell.

Permission rules and bounded loops are their own subject, and the advanced OpenCode guide covers the allow, ask, and deny patterns a scripted run should carry before it runs unattended.

Add Orchestration Only When You Need It

Oh My OpenCode is a community extension, not an OpenCode product, and it adds a layer that routes work across a team of specialised agents. It is mid-rename to Oh My OpenAgent, so expect both names in the wild.

Adopt it when you have already outgrown a shell loop, not before. The honest test is whether you can name the routing decision the orchestrator makes that your script cannot. If you cannot, the script is still the smaller thing that works.

OpenCode's own subagents cover a lot of ground first: General for parallel multi-step work, Explore for read-only codebase search, and Scout for external docs and dependency research. All three are invoked from inside one session.

Two mechanisms do that, and the OpenCode agents page documents both. A primary agent delegates to a subagent on its own, based on that subagent's description, and you can call one directly by mentioning it in the prompt, as in @general help me search for this function.

Primary agents are the separate case. Tab cycles between Build and Plan inside a session, and --agent names the agent for a scripted opencode run.

Keep Review from Becoming the Bottleneck

A fleet moves the constraint. Generation stops being the slow part, and reading diffs becomes it. Three sessions producing changes faster than anyone reads them just builds a backlog with extra token spend attached.

• Cap the fleet at the number of diffs you will actually read today.
• Give each session an acceptance test it must pass before you look.
• Watch the cost meter per session, not just the monthly total.
• Stop a session that has retried the same failure twice.

The last one matters most. An agent looping on a failure it cannot diagnose will keep spending, and a fleet turns one such loop into several running quietly in windows you are not looking at.

How This Compares with a Managed Board

Commercial editors have moved the same way, and Cursor's Agents Window is the clearest example. It collects parallel agents in one view and can isolate local tasks in worktrees, alongside cloud and remote-SSH runs.

The difference is who assembles it. A managed board gives you isolation and a status view out of the box; OpenCode gives you the primitives and expects you to choose the boundary. Neither answer is wrong, and they suit different people.

Fleet concern	OpenCode	Managed board
Isolation	You choose it	Built in; worktrees optional
Status view	Your terminal layout	Built-in sidebar
Scripting	Headless, fully scriptable	Limited to the product
Remote access	Any client, your network	Vendor cloud

The full head-to-head, including pricing and the agent layer, lives in Cursor vs OpenCode.

FAQ

Every OpenCode command, flag, and environment variable shown on this page was checked against OpenCode's own CLI, server, and agents documentation on August 10, 2026. The one command here that is not OpenCode's, the SSH tunnel, follows the OpenSSH manual page instead. The client and server split, the subagent trio, and the fleet guidance were checked on August 9, 2026.

How many OpenCode sessions can I run at once?

OpenCode does not publish a fixed session cap; the practical limit is your machine, your provider's rate limits, and how many diffs you can review. Start with two, add a third only when the first two are genuinely waiting on you rather than on each other.

Do parallel sessions share context?

No. Each session carries its own conversation and its own compaction history. Two sessions working on the same file will not know about each other's edits, which is why file-level or worktree-level separation matters more than session count.

Does OpenCode isolate agents from each other?

Not on its own. OpenCode gives you sessions and permissions; the isolation boundary is whatever you build with git worktrees, separate checkouts, or containers. That is the main operational difference from a tool that hands you managed worktrees.

Can I check on a run from my phone?

Yes, because OpenCode runs as a client talking to a server. The server binds to localhost and has no authentication by default, so prefer SSH port forwarding rather than changing the bind address. Exposing it on a network needs OPENCODE_SERVER_PASSWORD and TLS in front of it, because basic auth alone sends everything unencrypted.

Is a fleet cheaper than one session?

Usually not. Parallel sessions multiply token spend rather than dividing it, and each retry costs the same as it would alone. A fleet buys wall-clock time on independent tasks; it does not buy a discount.

When should I not run a fleet?

When the tasks touch the same files, when you cannot review the output as fast as it arrives, or when you are still tuning permissions. A single well-scoped session beats three sessions producing changes nobody has read.

Run the Smallest Fleet That Works

Two sessions on separate worktrees, each with a task you could describe in a sentence, covers most of what a fleet is actually for. Add the third when the first two are idle waiting on you, and add a script only when the work is repetitive rather than merely parallel.

Start from the OpenCode overview if the basics are not in place yet, and read the advanced guide before any session runs without someone watching it.