What is a sandbox lease?
A sandbox lease is the time a sandbox may run before it is paused or stopped for you, enforced by the platform rather than your code.
On Runtime every sandbox has a lease, and the host enforces it outside the
microVM, so it holds even if the management service is unavailable. A lease
lasts timeoutSeconds (1,800 by default, at most an hour ahead) and ends in a
pause or a stop, as onLeaseEnd says (the sandbox environment).
Why it matters for AI agents
An agent can crash, lose its connection, or loop without end. Whatever happens to the process that created a sandbox, the lease is the promise that the machine will not run, and bill, forever. It is also a stopping condition for work the agent started inside: a runaway build or a hung server ends when the lease does.
The lease is a timer on the server, not a setTimeout in your program, which
is why it survives your program dying.
The lease on Runtime
| Part | What it does |
|---|---|
timeoutSeconds |
Length of the first lease; 1,800 when omitted, at most 3,600 |
onLeaseEnd |
"pause" (the default) keeps memory and processes; "stop" ends the sandbox |
extend(seconds) |
Moves the end later, up to an hour ahead of now, as often as you need |
keepAlive |
Your process extends it once a minute so ten minutes remain, until released |
persistent: true |
Paid only: the server renews the lease while the account has credit |
| A wake | Starts a fresh lease of the sandbox's own timeoutSeconds |
maxCostMicros |
Refuses the create if its first lease would cost more |
| Daily spending limit | A renewal past the key's limit fails; the sandbox pauses or stops at lease end |
A sandbox whose lease ends with "stop" stops at once, so run sync after
writes to a volume that must be kept (JavaScript).
Set, extend and hold a lease
TypeScriptimport { Sandbox } from "withruntime";const sbx = await Sandbox.create({ timeoutSeconds: 900, onLeaseEnd: "stop" });console.log(sbx.info.expiresAt); // when the lease endsawait sbx.extend(600); // ten more minutesconst release = sbx.keepAlive({ marginSeconds: 1800 }); // held while this runsrelease();await sbx.stop();Pythonfrom withruntime import Sandboxsbx = Sandbox.create(timeout_seconds=900, on_lease_end="stop")sbx.extend(600)release = sbx.keep_alive(margin_seconds=1800)release()sbx.stop()keepAlive suits a job or notebook that owns the sandbox: when the process
exits, extensions stop and the lease runs out on its own. For a server that
should outlive every process, persistent: true with a maxTotalCostMicros
ceiling is the tool (keep a sandbox running).
Pause or stop at the end?
Choose "pause" when the agent may come back: the sandbox keeps its state
for 1 to 365 days and wakes on the next request. Choose "stop" for one-off
tasks such as a test run or a single code execution, where nothing inside is
worth keeping.
Related
Facts on this page were checked on 25 September 2026.