Skip to content
UseAgent

Engineering · Architecture · Sandboxes

AI agent sandbox architecture: keep the control plane outside

Our AI agent sandbox architecture: auth, secrets, the event log and the gateway stay outside the sandbox, and engines run inside as replaceable adapters.

Abhishek7 min read
On this page

Our first AI agent sandbox architecture let the browser talk straight to the agent process inside its sandbox, through the session UI that ships with the engine. It broke in ways we could not fix from the outside. Bun's default 10-second idle timeout killed held-open prompt requests. We raised it to the 255-second maximum and turns longer than four minutes still errored in the browser. Daytona's preview proxy sometimes buffered the event stream. A Claude Code thread reloaded to an empty timeline because our renderer only understood OpenCode's events.

On 2026-08-05 we threw that version away and rebuilt around a few decisions we don't reopen: no engine UI embedded in ours, the trusted control plane stays outside the sandbox, engines are rented one-shot workers, and the thread is backend truth. This is what lives where now, and what the split paid for.

Our AI agent sandbox architecture treats the sandbox as hostile

Treat the sandbox like a laptop lent to a stranger. The agent runs shell commands there, installs packages, opens whatever page a prompt injection pointed it at. Anything inside can be read by the agent, and anything the agent reads can end up in a commit, a log line or a model's context.

So the split looks like this:

Outside the sandbox (control plane) Inside the sandbox
Auth, org scoping, sessions The engine runtime: Claude Code, Codex or OpenCode
Postgres: runs, steps, raw provider events, canonical events The repo checkout and working files
The per-thread command lane, admission, fleet leases A terminal, a browser, a desktop
Org secrets and provider keys A short-lived capability token
The provider gateway and the tool gateway
Slack, GitHub and email connectors with their outboxes

The backend is Bun, Hono and Postgres through Drizzle. It is the only thing that holds credentials, and the only thing the browser talks to.

Keys stay with the gateway, never in the sandbox

Production runs sandbox secret delivery in gateway-only mode. Decrypted org secrets exist in backend memory only as values to redact from output. The sandbox's environment is empty of them, so are its secret files, and so is the list of secret names. When the agent needs a model, a GitHub write, a Gmail search or a Slack post, the request leaves the sandbox and goes to our gateway.

What the sandbox holds is a short-lived HMAC capability carrying org, user, thread, run, scope and expiry. Before each tool call the gateway re-resolves exactly one currently running, authorized run for it. Expired token, finished run, wrong thread: the call fails closed. Model traffic goes through a provider gateway that attaches the key server-side and finishes its retries before the sandbox sees a response. The security page has the short version of this boundary.

Approvals sit on the same line. A gated tool pauses the run, a person decides, and the run resumes with a one-shot capability bound to those exact arguments. The agent never holds anything it could replay for a different call.

Codex on a ChatGPT plan was the awkward case, since the login is OAuth state we will not copy into a sandbox. The backend keeps that state and hands the runtime a one-use relay URL bound to tenant, user, thread, run, model and sandbox generation. The sandbox only runs Codex's exec-server. More on that in running Codex on your ChatGPT plan in the cloud.

Engines are one-shot adapters, not services we host

Each thread is sequential. A per-thread advisory lock lets the worker claim the oldest queued command only when nothing else in that thread is dispatched. For each run it calls the engine's driver once: start or resume the native session, deliver the prompt, stream events, settle. The engine runtime stays resident in the thread's sandbox between turns. From the control plane's side every run is one shot.

Adapters keep each engine native. Claude Code speaks its own event grammar, Codex its own, OpenCode its own, and we don't make them speak ours. We translate afterwards into one canonical event format stored in Postgres. When we wrote the OpenCode translator, one real run's 1,188 native frames became 911 canonical events with zero unmapped, and the timeline rebuilt from canonical events matched the old renderer byte for byte: 281 tool rows, same order. Every source frame gets a recorded disposition, including the ones we suppress on purpose, so "the translator hides nothing" is a test, not a promise.

We also deleted the compatibility lane. For a while Claude Code ran through an ACP bridge. Once every engine had a native driver, ACP went, and the rule became simple: an engine has a native driver or it isn't an engine. If a sandbox provider can't boot an engine's native runtime, readiness reports that pair unsupported and the run stops before the turn starts. It never quietly falls back to a different engine.

The UI renders the event log, never a live process

This is the part that fixed the original bugs. The browser never talks to the sandbox. Raw provider events are written to Postgres before they're published, each run's canonical events are sealed through an outbox, and the browser reads one thread-scoped SSE stream that sends a snapshot, replays from a cursor and then goes live. A reload, a dead sandbox and a backend restart look the same to the UI. Fetch, replay, continue. The one-stream-per-thread post covers why the stream is per thread and not per run, and event-sourced agent runs covers the log itself.

One lane is deliberately not durable. Live answer and reasoning deltas go through a process-local buffer that is never reconnect truth and gets cleared when the run settles. Typing animation does not need a database row.

Every channel enters through one door

The web composer, Slack mentions, schedules, skills and child sessions all call the same function, acceptRunCommand. It validates the engine and model, writes the run and its command in one transaction, dedupes retries by org and payload fingerprint, and publishes a signal after commit. A new channel is a thin adapter into that call plus an outbox for its replies. Slack's adapter only translates events, derives an idempotency key from Slack's event id and owns its reply outbox. Ordering, cancellation and boot recovery come from the door. That is also why a run started from Slack shows up in the web app immediately. See an AI coding agent in Slack.

What the split bought us

Sandbox vendors turned into plugins. Daytona, Cube (which speaks the E2B protocol) and Box each ship as a package that exports one plugin: credentials, home directory, whether it runs as root, how preview links authenticate. Adding a vendor is a new package and one registry line. Nothing else in the backend switches on a vendor name. We have moved hosted sandboxes from a self-hosted Cube stack to E2B's cloud, tried Box and moved off it within a week, and added a developer's own machine as a provider, all without touching engines or the UI. The numbers from that are in E2B vs Daytona for coding agents.

Runs outlive the control plane. The turn lives in the sandbox runtime and the record lives in Postgres, so a fresh backend can find the native session and follow it. On 2026-10-11 we recreated the production backend mid-turn on purpose. OpenCode finished. Claude Code parked and then settled. That one test is why our deploys stopped waiting for those engines, which deploying long-running AI agents goes through in detail.

What it cost

One backend per database. The SSE fan-out and the barrier that seals a run's canonical events both live in one process. Two backends on one database would split the realtime stream, and one could seal a run while the other was still writing to it. So the backend takes a session-level Postgres advisory lock at boot, and production sets REQUIRE_SINGLE_BACKEND so that losing the race is fatal: the second process logs "Refusing to boot. Run exactly one backend per database." and exits.

Boot recovery is global. On start the backend scans every active command in the database and adopts, parks or fails its run. Correct for one backend. Destructive for two. During development several of us shared one dev database, and booting a second backend against it reconciled other people's in-flight runs into failures. Every test stack gets a throwaway database now.

The gateway hop costs time if you forget to cache. In September a computer-use tool call took 4 to 10 seconds against roughly 1.5 seconds of real work in the sandbox, because the gateway re-checked the desktop before every call. Caching readiness per sandbox for 60 seconds, cleared on any failed command, fixed it.

And Codex on the subscription relay is still the exception to restart survival. The relay lives in the backend process, so a Codex turn on a ChatGPT plan has to drain before a deploy, while OpenCode and Claude Code ride through.

The control plane, the engine adapters and the sandbox contract are all in the open-source repo; backend/src/engines and packages/sandbox-contract are the places to start.

Frequently asked questions

Should an AI coding agent have API keys inside its sandbox?

We don't put them there. In production the sandbox environment, its secret files and even the list of secret names are empty; the agent gets a short-lived capability and every model or integration call goes through a gateway that adds credentials server-side.

What is a control plane for AI agents?

It is the trusted service that owns auth, org scoping, the durable record of each run, scheduling, secrets and outbound integrations. The agent and its sandbox are workers it rents per thread and can replace.

Can I run two UseAgent backends against one database?

No. Realtime fan-out and the step that seals a run's events are process-local, and boot recovery reconciles every in-flight run in the database. Production takes a Postgres advisory lock at boot and a second backend refuses to start.

All posts →

Hand your next task
to a coding agent.

UseAgent runs Claude Code, Codex and OpenCode in cloud sandboxes. The core is open source, so you can read the code or host it yourself.