# Sandbox lifecycle

The sandbox lifecycle: create one for a task, run commands in it, pause it to keep its state, and kill it when the work is done. Runs do all of this for you; the SDK lets you do it yourself.

Every run gets its own sandbox: a small Linux VM with a copy of the repo and nothing else. It starts in under a second, has no outbound network unless you allow it, and is wiped when the run ends. You can also make sandboxes yourself, to try a command, reproduce a bug, or prepare a fixture before a run.

![One sealed cell per task. The repo is copied in, the agent works inside, its call to the network stops at the wall, and only the diff leaves before the cell is wiped.](/illos/agent-sandbox.svg)

> [!NOTE]
> A sandbox runs for up to 24 hours on Team and 1 hour on Hobby. For longer work, [pause it](/sandbox/persistence): pausing resets the clock, and its disk and memory are kept until you resume or kill it.

## Create a sandbox

A sandbox stays up until its timeout runs out. The timeout is in milliseconds and counts from the last command you ran, so a busy sandbox is never cut off mid-task.

```ts TypeScript {5}
import { Kestrel } from "@kestrel/sdk";

const kestrel = new Kestrel();
const sandbox = await kestrel.sandboxes.create({
  repo: "acme/web-app",
  timeoutMs: 600_000, // 10 minutes after the last command
});
console.log(sandbox.id, sandbox.state); // "sbx_41c9", "running"
```

```python Python {6}
from kestrel import Kestrel

kestrel = Kestrel()
sandbox = kestrel.sandboxes.create(
    repo="acme/web-app",
    timeout_ms=600_000,  # 10 minutes after the last command
)
print(sandbox.id, sandbox.state)  # "sbx_41c9", "running"
```

## Run a command

```ts TypeScript
const result = await sandbox.commands.run("npm test -- checkout");
console.log(result.exitCode, result.stdout);
```

```python Python
result = sandbox.commands.run("npm test -- checkout")
print(result.exit_code, result.stdout)
```

## The states

| State | What it means | Billed |
|---|---|---|
| `starting` | The VM boots and the repo is copied in. Usually under a second. | No |
| `running` | Commands run. The timeout counts down between them. | Sandbox minutes |
| `paused` | Disk and memory are saved and the VM is stopped. | Storage only |
| `killed` | The VM and its disk are gone. This can't be undone. | No |

## Change the timeout while it runs

```ts TypeScript
await sandbox.setTimeout(30 * 60_000); // 30 more minutes from now
```

```python Python
sandbox.set_timeout(30 * 60_000)  # 30 more minutes from now
```

## Kill a sandbox

Killing is immediate. Anything not downloaded or snapshotted is lost.

```ts TypeScript
await sandbox.kill();
```

```python Python
sandbox.kill()
```