How to keep a sandbox running

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

Which to use

Need	Use	When it pauses
A job, an agent run, a notebook or a CI step	Nothing: the default	After 300 seconds with nothing happening
A server, bot or dev box that runs with nobody watching	`persistent: true`	Never on its own. You stop it
A sandbox created with a time limit, held past it	`keepAlive()`	When your process lets it go

A persistent sandbox

TypeScriptimport { Sandbox } from "withruntime";const server = await Sandbox.create({  name: "api-bot",  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 sandbox

Pythonfrom withruntime import Sandboxserver = Sandbox.create(name="api-bot", 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 sandboxes create --persistent --name api-bot)runtime sandboxes update "${id}" --persistent on --max-total-cost 50   # dollarsruntime sandboxes restart "${id}"

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

A stopped persistent sandbox stays in runtime ls while its disk is kept. To be done with it, turn persistence off: runtime sandboxes update "${id}" --persistent off deletes a stopped sandbox's disk and frees its name. On a running sandbox, it ends the disk charge immediately.

A long job needs nothing

A sandbox created without timeoutSeconds runs for as long as its job does. A two-hour training run is not cut off at one hour. When the job ends and nothing else happens, the sandbox pauses itself.

TypeScriptimport { Sandbox } from "withruntime";const worker = await Sandbox.create();await worker.exec("python3 train.py", { timeoutMs: 7_200_000 }); // two hoursawait worker.stop();

Pythonfrom withruntime import Sandboxworker = Sandbox.create()worker.exec("python3 train.py", timeout_ms=7_200_000)  # two hoursworker.stop()

keepAlive() is for a sandbox created with a time limit. It moves the limit on from your process, keeping ten minutes ahead. It keeps doing this until you call stop(), or until you call the function it returns.

What each costs and keeps

Setting	Detail
`persistent`	Paid only; runs until you stop it, idle or not, while the account has credit
`maxTotalCostMicros`	The most the sandbox may cost over its whole life; `--max-total-cost` in dollars
After a stop	The disk is kept, billed as paused storage, and `restart()` starts it again
Reserved disk rate	153 microdollars per GiB-hour, the volume rate, about $0.11 per GiB a month
Idle pause	300 seconds with nothing happening by default; `idlePauseSeconds` sets 0 (never) or 60 to 86,400
Compute while running	$0.025 per active vCPU-hour of measured CPU, $0.0075 per reserved GiB-hour
Out of credit	Sandboxes and stored items are kept 30 days with a notice (seven without a purchase or saved card), then deleted

Mistakes to avoid

Making a sandbox without credit persistent. Persistence is for paid sandboxes. Once the account holds credit, its sandboxes are paid and can be persistent.
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.
Setting a time limit you then have to keep extending. Leave timeoutSeconds out. The sandbox then runs while it works, with nothing for your process to keep alive.
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.

Extend a sandbox's time limit, for one created with a limit.
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 October 2026.