# Lifecycle

Each sandbox is in exactly one state. The same names are used in the API, CLI, dashboard, webhooks and logs.

| State | Meaning | Billed? | How to leave it |
|---|---|---|---|
| `creating` | Being prepared | From machine assignment, if it starts | Automatic |
| `ready` | Running; commands work | **Yes** | `sleep`, `stop`, `delete`, or the auto-stop |
| `sleeping` | Memory and disk saved; RAM released | **Yes**, like `ready` | `wake`, or any incoming request or command |
| `stopped` | Disk saved; machine released | No, free for 14 days | `resume`, `fork`, `delete` |
| `archived` | Disk in cold storage, after 14 days | $0.012/GB-month | `resume` (slower), `delete` |
| `failed` | Could not start or was lost | No | `resume`, `delete` |
| `deleted` | Erased | No | None |

Conditions can accompany a state: `migrating`, `degraded`, `recovering`, `hydrating`, `nested_active`.

## Sleep or stop?

| | Sleep | Stop |
|---|---|---|
| Keeps running programs | **Yes** | No |
| Comes back in | Under 2 s (target) | A few seconds, then hydration |
| Automatic | When idle, if you turn on `--sleep auto` | At the auto-stop, an hour by default |
| Kept for | Memory for up to 7 days, then becomes `stopped` | At least 14 days, free |

## Auto-stop

Every sandbox has an auto-stop. It defaults to one hour, counted from creation or the last resume or wake, not from your last command. The maximum is 30 days, or none: send `ttl_seconds: null`, or `--no-auto-stop` on the CLI. While an agent prompt is running when the time comes, the deadline moves one auto-stop later, and keeps moving until no prompt is active. During the [trial](../start/trial.html), an auto-stop of 2 hours or less is required.

```sh
harebox new --name timed --ttl 1800
```

## When idle sleep happens

Idle sleep is opt-in: create the sandbox with `--sleep auto`, or set `sleep.mode` to `auto`. Then it sleeps after its idle window (default 120 s) when **all** of these hold:

- CPU is under 2% and network is under 1 KiB/s.
- There is no SSH, desktop or exec session, and no command still producing output.
- No harness turn is queued or running, and no LLM stream is open through the proxy.
- No nested VM is running.

**What does not happen during sleep.** Cron and timers inside the VM do not fire, and connections you hold open may break. If you need these, set `--sleep never`, or use `harebox schedule new` to wake it on a timetable.

## What survives

| | Sleep | Live migration | Fork from `ready` | Stop and resume |
|---|---|---|---|---|
| Files, packages, Docker data, build cache | Yes | Yes | Yes, exact | Yes |
| Running programs and memory | Yes | Yes | Yes, copied | **No** |
| Conversations and agent memory | Yes | Yes | Yes | Yes |
| Open connections | Often break | Yes | No | No |
| Public IP | Yes | Yes | New | New, unless reserved |
| Public URLs and firewall rules | Yes | Yes | New URL; rules copied | Yes |

## Committed, best effort, unsupported

**Committed:**

- Billing stops when a stop begins, and saving time is not billed. A sleeping sandbox is billed like a running one.
- An automatic stop (auto-stop deadline, end of a Spot notice, end of the memory window, a budget) bills up to the moment it fell due, even if the machine stops a few seconds later.
- A failed save never loses your running VM. It keeps running, and the meter pauses.
- Forks never share identity, keys or entropy with their source.
- Stopped disks are kept for at least 14 days, then move to paid cold storage rather than being deleted.

**Best effort:**

- Wake and start times. Targets by kind of host, and live figures once measured, are at `GET /regions`.
- Keeping connections across sleep.

**Unsupported today:**

- Memory snapshot or sleep while nested guests are running. Check `capabilities.memory_snapshot`.
- Live migration of most GPU sandboxes. They get a scheduled restart with at least 72 hours' notice.

**Durability:** on Shared, an `fsync` is durable on the local disk, and reaches off-host storage within 30 s. If a host dies, up to 30 s of writes can be lost. Replicate at application level if that matters.