Why Your AI Refactor Tool Should Run in a Sandbox

When an AI coding agent runs in your terminal with full access to your repo, it can do useful work and it can also do harmful work, and most days you cannot tell which until you've read the diff. OpenAI's recent cookbook example shows the pattern that fixes this: don't run the agent in your working directory at all. Spin up a fresh sandbox, give it the files it needs, let it produce a patch, then review the patch yourself before it touches anything you care about.

The split is between a trusted host process (your code, running on your machine, with your credentials and your real repo) and a sandboxed execution environment (a throwaway container or microVM that holds only what's needed for one task). The agent code lives in the sandbox; the orchestration lives in the host.

Per OpenAI's cookbook example, the sandbox is usually a Docker container (a fresh Python 3.14 image per task), though the same pattern works with E2B or Cloudflare Workers, the serverless edge-computing platform from Cloudflare for running code globally, as the isolation layer. Inside the sandbox the agent can run commands, edit files, run tests. None of that touches your real machine. When the task ends, the sandbox is deleted, taking any side effects with it.

The trust boundary is the key idea. Credentials, API keys, MCP servers, audit logging: those stay in the host process. The sandbox sees only the files and the task brief.

Two reasons, and they're both starting to fall away.

The first is friction. Spinning up a fresh sandbox for every task costs some seconds of latency and some megabytes of disk. If you're doing twenty small edits an hour, that's a noticeable tax. The interactive coding flow most of us use today (Claude Code, Cursor, Copilot in-editor) prioritises speed over isolation. The trade made sense when AI coding was mostly autocomplete; it makes less sense when agents are running multi-file refactors unattended.

The second is complexity. Wiring up Docker, mapping volumes correctly, handling the patch-extraction step at the end: it's all real engineering. Doing it badly creates new failure modes (sandbox can't reach the test runner, mounted volume leaks state, patch fails to apply cleanly). The cookbook pattern matters because it makes the engineering reusable.

Both reasons are eroding. Sandbox startup latency is dropping (E2B and Cloudflare Workers measure in tens of milliseconds rather than seconds). The orchestration libraries are maturing. The pattern that today requires bespoke setup will be a one-line config in mainstream tools within a year.

Six steps, each one belonging clearly to either the host or the sandbox.

An auditable patch has four properties. It's a standard unified diff (the same format git apply consumes), so any developer can read it without special tooling. It's small enough to review (because the host split the work into small tasks). It comes with a complete audit log showing every shell command the agent ran. And it's bundled with a structured result that names what was attempted and what succeeded.

That bundle is the thing that makes the difference between "trust the agent" and "verify the agent". Without the audit log you cannot tell whether the agent ran tests, whether it cheated by skipping a step, whether it tried something destructive before deciding against it. With the audit log you can grep for shell commands you don't recognise, spot patterns of repeated failure, and decide whether to apply the patch based on what actually happened rather than the agent's self-reported summary.

This is the same shift code-review tools went through fifteen years ago: from "trust the developer's commit message" to "see the actual diff". Agents need the same scrutiny, for the same reasons.

Three categories where sandboxing is clearly worth the engineering cost.

Bulk migrations. Anything you'd describe as "update this pattern across the whole codebase" (replace deprecated APIs, change a library version, rename a function). The work splits naturally into small tasks, each task has a clear pass/fail check (tests), and the volume justifies the orchestration overhead.

Anything touching production config or secrets. If the task might involve reading env files, deploy scripts, infrastructure-as-code, the sandbox is the only safe place for the agent to operate. Even if you trust the agent, running it in a sandbox means a misconfiguration cannot leak production secrets to its training data, its provider's logs, or anywhere else.

Untrusted or experimental agents. If you're trying out a new agent framework, a new model, or a workflow you don't fully understand yet, run it in a sandbox first. The marginal cost is small; the marginal safety is large.

For day-to-day interactive coding (you, in Claude Code or Cursor, making one edit at a time), the sandbox overhead probably isn't worth it. The existing tools have approval prompts and easy undo, which cover the common cases. The pattern wins when the agent is running unattended on something more than one file.