Put OpenCode’s whole workbench in the sandbox
Suppose a coding agent edits src/parser.ts and runs npm test. The tests pass. That’s reassuring until you realize the editor changed the laptop’s checkout and the shell tested a different copy in the sandbox. Moving just the shell off your machine can leave the agent confidently checking code it never touched.
Our first Mainbrella integration for OpenCode puts its coding server in the sandbox. File reads, edits, searches, and commands use the same guest checkout, while the interface stays local. OpenCode already has workspace adapters for connecting to a remote server, so we could do this with Mainbrella’s existing command and protected-preview APIs, without adding dependencies or changing the backend.
The implementation is in draft PR #53943. As of October 8, it’s experimental, hasn’t shipped upstream, and still needs live cloud validation. Moving the server was straightforward enough. Keeping the client connected when its access URL expires took more work.
One path should mean one file
OpenCode is an open source coding agent with terminal, desktop, and IDE interfaces. Its tools inspect repositories, edit files, and run commands; its permission rules decide whether those operations are allowed, denied, or need your approval. Issue #48411 asks for easier permission controls, sandboxed execution, and an optional model to review approvals. This PR tackles where approved operations run. The approval rules still apply.
We could try synchronizing two checkouts to avoid the parser example above, but then every read, write, and test would depend on getting that synchronization right. That’s a lot of machinery to recreate what a shared filesystem already gives us. The diagram’s shell-only design is hypothetical; the PR uses the second arrangement.
opencode serve runs OpenCode’s headless server, and the experimental workspace adapters in the source we used can point a client at it. Our adapter supplies that address. The existing tools run beside the guest checkout without needing a remote implementation of each file operation.
The agent runtime, project tooling, and model-provider authentication therefore live on the guest. If that guest becomes unavailable, the operation fails. Quietly falling back to the laptop would defeat the whole point of choosing a sandbox.
Start with a prepared machine
This version expects a running Node sandbox that you own. Install the same OpenCode build there, check out the project, and configure its model credentials. Small or larger is preferable for the server and project tooling. The guest needs opencode, tmux, and curl on its PATH; the adapter won’t copy your laptop’s files, SSH keys, credentials, or environment over for you.
You give it the container slot and exact creation timestamp, because small can refer to a different machine after the first one stops. The adapter checks that the selected generation is running and includes that identity in command and preview requests. If the machine is gone, you have to choose what to do next. It won’t substitute whatever happens to occupy the slot.
The launch command has a 20-second timeout, which would be a pretty short coding session. We start OpenCode in detached tmux so the server can outlive that request. A dedicated socket and ownership file tie it to one OpenCode workspace. Before returning, the launch checks the version and waits for a healthy endpoint. Another workspace’s ownership marker or an occupied HTTP port causes it to refuse the launch.
Tmux only detaches the process. The machine still has idle and hard deadlines, and a quiet event stream doesn’t keep it alive. You can leave the interface open over lunch and come back to an expired sandbox.
| Resource | Adapter’s responsibility |
|---|---|
| Its tmux server | Stop it after checking ownership. |
| Its known preview grant | Revoke it for the selected generation. |
| The prepared sandbox | Leave it running. You control save and stop. |
| Unexported guest files | No automatic snapshot. Save or export before the machine stops. |
Manual preparation is a pain, but it lets us propose the workspace integration without also asking upstream to accept an installer, repository transfer, and machine provisioning. Those are useful follow-ups if the adapter is accepted.
Reconnecting after the address expires
Mainbrella’s protected preview gives the client access to the guest server’s HTTP port. The URL contains a bearer token in its hostname, so anyone with that address can use the grant. The account API key goes only to the configured Mainbrella API origin to request access. The guest server and preview never receive it.
The adapter asks for an hour of access, shortened when necessary to fit the machine’s hard deadline. After checking the destination and server health, it saves the connection receipt in private local state. A credential-bearing URL doesn’t belong in public workspace metadata. On Unix, the receipt directory uses mode 0700 and the files use 0600; the checks and launch script are in the adapter source.
After the recorded grant expires, resolving the workspace target can request another one. The client gets a new URL for the same server and files, provided the machine is still running. Renewing access doesn’t extend the machine’s lease, and its idle deadline may stop it before the hard deadline shown here.
OpenCode’s event synchronizer originally resolved the target before entering its reconnect loop. Every retry still used the expired URL. We moved resolution into each connection attempt so a reconnect can pick up the new address and synchronize history there. The regression case closes the first stream, returns a different route from the adapter, and checks where the next connection goes.
We also had to keep credentials from crossing into the wrong server. Forwarded workspace requests drop the local server’s Authorization header, cookies, and auth_token query parameter, while retaining adapter-supplied remote headers and a remote terminal’s ticket. Transport errors log the status and error category, without the secret URL or response body. A useful error log shouldn’t double as an access grant.
The preview gateway strips Authorization itself, so the guest server starts without OpenCode’s Basic authentication and relies on the preview grant for incoming access. Any other route to that port would need its own access control. Guest processes can still read the guest’s model credentials, and the PR doesn’t add network filtering or a model that reviews approvals.
A lost reply can leave access behind
Suppose Mainbrella creates a grant but the response never reaches the adapter. Preview issuance has no idempotency key in the API this PR uses, so retrying the POST can create a second grant. Listing grants won’t recover the first URL either; the list returns metadata without the secret. We could get a working connection on retry and still have an unrecorded grant sitting there.
Retry the POST immediately
The second grant may work, but the first can remain active without a receipt. The adapter still doesn’t know what access it needs to revoke.
Save a pending marker first
A missing or ambiguous response leaves the marker in place. The adapter refuses another grant until the operator resolves the earlier attempt.
We use the pending marker, which means recovery is manual in this draft. Inspect and revoke the uncertain grant for that exact generation, then reset the marker using the recovery instructions. If cleanup fails, the private receipt survives even if OpenCode removes the workspace row. Deleting the evidence would make a messy recovery worse.
This is where backend support would help. If the adapter could ask what happened to a particular issuance, it could recover without making you inspect grants by hand.
Try it with one file
Use this build of our fork on both sides; a stock release doesn’t include the adapter. Two development builds can both report version local despite containing different code, so match their source commits too. Prepare the guest project and model credentials, supply the account key through your usual secret environment mechanism, and identify the guest:
# MAINBRELLA_API_KEY is already set securely.
export OPENCODE_EXPERIMENTAL_WORKSPACES=true
export MAINBRELLA_CONTAINER_ID=small
export MAINBRELLA_CREATED_AT='2026-10-08T12:00:00.000Z'
export MAINBRELLA_DIRECTORY=/workspace/my-project
opencode
The slot and timestamp above are examples: replace them with the complete values returned for your running machine. Create a workspace and choose Mainbrella in the experimental picker. The setup guide covers optional ports, a local API origin, and recovery.
Local checks include launching OpenCode through tmux, reading a file, and shutting the server down. They don’t establish that a hosted agent run completes successfully; live cloud validation remains open for this draft. A preview revoked outside the adapter also won’t be replaced automatically before its recorded expiry. If the server crashes or the machine stops, the adapter doesn’t restart the server or replay the model’s work elsewhere.
Start by changing one harmless guest file and checking that the test runner sees the edit. Then delete the OpenCode workspace. Its server should be gone, and the machine you prepared should still be running.