Building AI Coding Agent Sandboxes Without Starting a Container First

Most AI coding products eventually need a sandbox. The agent has to mount files, edit them, run commands, inspect output, and show the user what changed. The common default is to start a container for every session. That works, but it is not always the right first move.

For many agent tasks, the first useful environment can live in the browser. The agent needs a filesystem, Node.js-style commands, supported Python, package installs, and a preview surface. It does not necessarily need a server workspace before the first file is opened.

What the agent actually needs

An agent sandbox needs a few concrete capabilities:

• A writable project filesystem.
• Process execution with stdout, stderr, exit codes, and cancellation.
• Package installation that is fast enough for interactive use.
• A way to preview web apps and generated artifacts.
• Persistence across reloads or interrupted sessions.
• A fallback path for tools the browser cannot run.

The last point is the important one. Browser-first does not mean browser-only. It means the browser handles the work it can handle, and a managed server runtime takes over when native capabilities are required.

Start with the cheap host

Browser execution is a strong default for early agent steps:

• Reading and writing files.
• Running JavaScript and TypeScript fixtures.
• Starting simple Node.js HTTP servers.
• Running supported Python through Pyodide.
• Generating SVG, JSON, Markdown, and static assets.
• Rendering isolated previews.

Those tasks are common in tutorials, demos, coding assistants, and small reproduction environments. Starting them locally in the tab reduces startup latency and avoids creating a server session before the work has proved it needs one.

Keep the API stable when the backend changes

The host product should not need separate agent integrations for local and remote execution. The useful abstraction is a single runtime object:

import { Runtime } from '@verklet/sdk';

const runtime = await Runtime.boot({
  projectId: 'prj_your_project_id',
  backend: 'auto',
  persistenceKey: 'agent-session',
});

await runtime.fs.writeFile('/workdir/index.js', 'console.log("ready")');
const process = await runtime.spawn('node', ['index.js']);

With backend: 'auto', the runtime can begin in the browser. If the agent later runs uv, asks for native Python wheels, or calls a native Linux tool, the workspace can promote to the server backend.

The UI keeps listening to process and diagnostic events. The agent keeps using the same filesystem and spawn calls. The backend shift is an implementation detail exposed through capabilities, not a second product surface.

Promotion preserves context

Promotion is only useful if the agent does not lose its work. A practical hybrid runtime snapshots the browser filesystem, creates a server session, mounts the snapshot into the server workspace, and continues from there.

That matters for agent UX. The user should not see "we need to restart in a container" after the agent has already written files. The server path should feel like a capability upgrade: same project, same files, more tools.

Previews are part of the sandbox

Agent products often focus on command execution and forget previews. For web work, the preview is where the user decides whether the agent succeeded.

A browser-first runtime can expose preview URLs through an isolated preview origin. When a process opens a port, the preview can render in an iframe without publishing a public tunnel or giving generated code the host application's origin. That is useful for security, screenshots, stateful demos, and user review.

For server-backed sessions, the same runtime events can still describe ports and readiness. The host UI should not care whether the responding process started in a worker or on a managed server.

Containers are still the right answer for some work

Some agent tasks need Linux immediately:

• Native Python wheels.
• uv workflows.
• Native package managers.
• Long-running server processes.
• Larger memory ceilings.
• Workspaces that should persist beyond browser storage.

Those are good reasons to start with backend: 'server' or to let backend: 'auto' promote. The design mistake is making every tiny scratchpad pay the same cost as a native build.

The product shape

For AI coding agents, the browser-first architecture gives a clean default:

1. Boot a runtime in the browser.
2. Mount or generate the project files.
3. Let the agent edit, run commands, and inspect output.
4. Show previews through an isolated preview origin.
5. Persist snapshots for reloads.
6. Promote only when the command stack needs server capabilities.

That makes the sandbox feel immediate for simple work and credible for harder work. The agent gets an execution environment quickly, and the product keeps a path to real Linux when the browser is the wrong host.