How to keep a sandbox running

Create it with persistent: true to keep a paid sandbox running while credit lasts, or call keepAlive() to hold it from your process.

On Runtime a sandbox can run for as long as the account has credit, with a spending ceiling you set, and still bill only the CPU it uses. A persistent 2 vCPU, 4 GiB sandbox that waits most of the day costs $0.03125 an hour, about $22.50 over 30 days, and $0.08 an hour at most with both CPUs busy (pricing, checked 25 September 2026). After a stop its disk is kept, so it restarts where its files left off.

Two ways, for two jobs

A persistent sandbox

TypeScriptimport { Sandbox } from "withruntime";const server = await Sandbox.create({  name: "api-bot",  funding: "paid",  persistent: true,  maxTotalCostMicros: 50_000_000, // at most $50 over its life});await server.spawn("python3 -m http.server 8000");// Later: it was stopped, and its disk was kept.await server.restart();await server.update({ persistent: false }); // back to an ordinary lease

Pythonfrom withruntime import Sandboxserver = Sandbox.create(name="api-bot", funding="paid", persistent=True,                        max_total_cost_micros=50_000_000)server.spawn("python3 -m http.server 8000")server.restart()  # after a stop, from its kept diskserver.update(persistent=False)

Terminalid=$(runtime sandbox create --paid --persistent --name api-bot)runtime sandbox update "${id}" --persistent on --max-total-cost 50   # dollarsruntime sandbox restart "${id}"

A name stays held while its sandbox is stopped and persistent, so Sandbox.getOrCreate("api-bot") finds it and restarts it for you. An agent over MCP calls runtime_sandbox_manage with "action": "persist".

Keep it alive from your process

keepAlive() extends the lease so ten minutes remain, once a minute, until you call stop() or the function it returns. When your process ends, the lease runs out as usual and the sandbox pauses, by default.

TypeScriptimport { Sandbox } from "withruntime";const worker = await Sandbox.create({ keepAlive: true }); // on from the startconst release = worker.keepAlive({ marginSeconds: 1800 }); // or with optionsawait worker.exec("python3 train.py", { timeoutMs: 7_200_000 });release();await worker.stop();

Pythonfrom withruntime import Sandboxworker = Sandbox.create()release = worker.keep_alive(margin_seconds=1800)worker.exec("python3 train.py", timeout_ms=7_200_000)release()worker.stop()

What each costs and keeps

Mistakes to avoid

• Making a trial sandbox persistent. Persistence is for paid sandboxes. Pass funding: "paid" (--paid) once the account has credit.
• No ceiling. Without maxTotalCostMicros a persistent sandbox runs for as long as credit lasts. Set a ceiling, or a daily spending limit on the key (security).
• Starting the server with exec. A process started by exec ends with its command. Use spawn so the server keeps running.
• Counting on keepAlive after your script exits. It runs in your process; the lease stops renewing when the process does. Anything that must outlive the script needs persistent.
• Keeping it running only to keep its state. If nobody uses it for hours, pause it when idle instead; memory and processes come back on the next request.

Related

• Extend a sandbox lease by hand.
• Find a sandbox by name to reach a long-running one from anywhere.
• Run a background process for the server itself.
• Keep a sandbox running in the SDK reference.

Facts on this page were checked on 25 September 2026.