Lifecycle and keep-awake

When a sandbox sleeps, how to keep a busy sandbox awake, and how to wake it again.

A sandbox is a Firecracker microVM. It moves through these states:

`status`	Meaning
`creating`	The VM is booting. Wait for `running`.
`running`	The VM is live. You can run commands, read files, and open the shell.
`snapshotting`	A snapshot is in progress.
`hibernated`	Memory and files are saved and the VM is stopped. The id stays the same.
`stopped`	The sandbox is deleted.

When a sandbox goes to sleep

The platform puts a running sandbox to sleep (hibernates it) 2 hours after it started, unless it holds a keep-awake lease. The platform does not watch CPU or network activity. A sandbox that is still doing work is also put to sleep at 2 hours if nothing renews its lease.

Sleep keeps memory and files. Open network connections do not survive: when the sandbox wakes, your processes must reconnect to anything outside.

A sandbox that stays asleep for 14 days is deleted. Take a backup or copy your files out before then if you need them longer.

Keep a busy sandbox awake

A keep-awake lease tells the platform "this sandbox is still working". While the lease is in the future, the 2-hour rule does not put the sandbox to sleep.

One renewal lasts the number of seconds you ask for. The default is 600 (10 minutes). The maximum is 1800 (30 minutes). Larger values are reduced to 1800.
A renewal never makes an existing lease shorter.
Renew every few minutes while work runs. When work stops, stop renewing. The sandbox sleeps when the lease runs out (and it is more than 2 hours old).
To sleep at once, call hibernate. You do not need to wait for the lease.
Only a running sandbox can take a lease. A sleeping sandbox returns 409. Wake it first.
A wake starts a new 2-hour period with no lease.

A sandbox that never takes a lease behaves the same as before: it sleeps 2 hours after it started.

From your server

curl -X POST https://infra.omg.dev/v1/sandboxes/$SANDBOX_ID/extend \
  -H "Authorization: Bearer $OMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "seconds": 900 }'

The response is 204 with no body. GET /v1/sandboxes/{id} shows the current deadline as keepAwakeUntil.

With the SDK:

const sandbox = client.sandbox(sandboxId)
await sandbox.keepAlive(900)

From inside the sandbox

Code that runs inside the sandbox, for example a coding agent or its plugin, can renew the lease itself. It needs no API key:

curl -X POST http://169.254.0.1:9090/v1/sandbox/keepalive \
  -H "Content-Type: application/json" \
  -d '{ "seconds": 900 }'

{ "keepAwakeUntil": "2026-10-16T12:30:00Z" }

The address 169.254.0.1:9090 exists only inside each sandbox. A request to it always renews the sandbox it comes from, so one sandbox cannot keep another awake. Use this when the process that knows it is busy runs inside the sandbox.

Wake a sandbox

curl -X POST https://infra.omg.dev/v1/sandboxes/$SANDBOX_ID/wake \
  -H "Authorization: Bearer $OMG_API_KEY"

The sandbox resumes under the same id with its memory and files. The response has status: "running". With the SDK: await sandbox.wake().

A visit to the sandbox's preview URL by its owner also wakes it.

Check status

There are no self-serve webhooks yet. Poll GET /v1/sandboxes/{id} for the exact state of one sandbox. GET /v1/sandboxes lists all of them, but it shows only running, hibernated, or stopped (a booting sandbox shows as running). Both include keepAwakeUntil when the sandbox has taken a lease.

Delete a sandbox

DELETE /v1/sandboxes/{id} stops the sandbox and deletes it. Use this when you do not need the sandbox again. A sleeping sandbox does not run, but it is deleted after 14 days.