Tektona Docs

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.
`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`), so a crash is 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 (and still holds its disk) until it is deleted.

State	Meaning
`completed`	The workload exited cleanly (exit code 0).
`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.

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 running sandboxes.
Paused counts hibernated + suspended (so a crash-suspended sandbox shows here).
error, failed, completed, exited, deleting, and deleted are hidden from the sandbox lists by default. Tick Show deleted & errored to include them.
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.

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.

Sandbox States