Sandboxes
Isolated environments your code controls
Give a worker an isolated, long-lived environment with its own filesystem. Run commands, write and read files, clone repositories, and start background processes that keep running after the response is sent. Each sandbox is addressed by id, so an agent session can keep one alive across requests.
Sandbox Session
Sandbox
Persists across requests
Processes
3 completed
AI
Gateway credentials injected
Session Log
Commands run from a worker against one long-lived sandbox
Key Features
Run Commands
exec() returns stdout, stderr, and the exit code; execStream() streams output as it happens.
Background Processes
Start a build, a dev server, or a coding agent and check back on it from a later request.
Clone Repositories
gitCheckout() clones public or private repositories without writing credentials to disk.
Agent Ready
With ai: true, the sandbox receives gateway credentials so a coding agent can call models with no keys of its own.
Sandbox Binding
Reuse the same id across requests to keep files and processes alive for a session.
export default {
async fetch(request, env) {
const sandbox = env.SANDBOX.get("session-42");
await sandbox.gitCheckout("https://github.com/acme/app", {
depth: 1,
targetDir: "app",
});
const result = await sandbox.exec("pnpm test", { cwd: "app" });
return Response.json({
ok: result.success,
output: result.stdout,
});
},
} satisfies Ploy;