# 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](/docs/sandbox-environment#time-and-lifetime)).

## 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](/docs/javascript#volumes)).

## Set, extend and hold a lease

```ts check
import { Sandbox } from "withruntime";

const sbx = await Sandbox.create({ timeoutSeconds: 900, onLeaseEnd: "stop" });
console.log(sbx.info.expiresAt); // when the lease ends
await sbx.extend(600); // ten more minutes
const release = sbx.keepAlive({ marginSeconds: 1800 }); // held while this runs
release();
await sbx.stop();
```

```python check
from withruntime import Sandbox

sbx = 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](/docs/javascript#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

- [What is idle pause?](/glossary/idle-pause)
- [What is an agent loop?](/glossary/agent-loop)
- [What is an ephemeral environment?](/glossary/ephemeral-environment)
- [Security](/docs/security#lifetimes-and-storage)

Facts on this page were checked on 25 September 2026.