Lifecycle
Works locallyWorks in the local build today.
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 | 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 |
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, an auto-stop of 2 hours or less is required.
harebox new --name timed --ttl 1800
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.
| 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:
- 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.