Sandbox States
The lifecycle states a sandbox moves through, what each means, and how they appear in the CLI and dashboard.
Every sandbox reports a state that you see in tektona sandbox ls, the
sandbox detail page, and the dashboard. States fall into five groups: starting
up, running, paused, ended, and removal.
Starting up
A freshly created sandbox moves through a short series of transitional states before it is ready:
| State | Meaning |
|---|---|
creating | The request was accepted and the sandbox record exists. |
building_image | The image is being converted/prepared (first use of an image). |
scheduling | The platform is placing the sandbox on a host. |
queued | Every host is full. The sandbox waits for room instead of failing. |
starting | The VM is booting. |
These are brief and self-clearing. If something goes wrong here you end up in an
ended state (for example error on a placement or build failure).
Running
| State | Meaning |
|---|---|
running | The sandbox is live. CPU and memory are reserved, and SSH/VNC/ports are reachable. |
This is the only state that consumes CPU and memory. Disk is reserved in every non-deleted state, not just this one.
Paused (resumable)
Paused sandboxes are stopped but can be brought back with tektona sandbox resume (or automatically, if auto-resume is enabled). They keep their disk and
do not consume CPU or memory.
| State | Meaning |
|---|---|
hibernated | Paused with memory snapshotted to storage. Resumes to exactly where it left off, and survives the host being recycled. |
suspended | Paused and recoverable. A sandbox also lands here after an unexpected VM crash (reason vm_crashed), and after a hibernate whose memory snapshot could not be completed (reason partial_memory_image) — so both are recoverable rather than fatal. |
hibernating, suspending, resuming, and rebooting are the in-flight
versions of these transitions and clear on their own.
Ended
These states are terminal for that run. The sandbox still exists until it is deleted, and it keeps its disk — with one exception. A sandbox that broke before it ever ran has no disk to keep, so the platform releases its share of the machine within a few minutes. The record stays in your list.
A sandbox that fails because its program never started also gives back the cpu and memory it held. The platform stops its machine. This applies to a sandbox that comes back from a pause, a reboot or a fork too. Its disk stays until you delete it.
| State | Meaning |
|---|---|
failed | The user workload failed (non-zero exit, or the entrypoint never started). |
error | A platform-side failure, for example a build or scheduling error. |
Removal
| State | Meaning |
|---|---|
deleting | Teardown is in progress, and the sandbox is being removed from its host. |
deleted | Fully removed. It no longer counts toward any usage and is hidden from lists by default. |
tektona sandbox ls shows a sandbox in every state above except deleting and
deleted. Add --include-deleted to see those too.
Deletion is a soft delete: the record is retained for history, but the disk and compute are released.
How states appear in the dashboard
- Running counts only
runningsandboxes. - Paused counts
hibernated+suspended(so a crash-suspended sandbox shows here). error,failed,deleting, anddeletedare hidden from the dashboard sandbox list by default. Tick Show deleted & errored to include them.tektona sandbox lshides less: onlydeletinganddeleted.- Allocated usage per day charts are reservation-over-time
(resource-hours): CPU and memory accrue only while a sandbox is
running, while disk accrues for the whole lifetime (any non-deleted state) because the disk stays reserved until the sandbox is deleted.
Where states are recorded
Every transition is written to the sandbox's history with a timestamp, a
reason (for example idle_timeout, vm_crashed, user_resume), and the actor
that caused it. You can review it per sandbox in the detail view.