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 describe startup, normal operation,
host availability, pause, failure, 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. |
scheduling | The platform is placing the sandbox on a host. |
queued | No host can accept the sandbox now. The sandbox waits for capacity. |
starting | The VM is booting. |
A sandbox starts from a template, and the template already holds a built image,
so a new sandbox goes straight to scheduling. You can still meet
building_image on a sandbox created before that change.
These are brief and self-clearing. If something goes wrong here you end up in an
ended state (for example failed on a placement failure).
The platform excludes hosts with an unavailable egress gateway from new placements. Hosts accept new placements again after the gateway answers.
Running
| State | Meaning |
|---|---|
running | The sandbox is live. CPU and memory are reserved, and SSH/VNC/ports are reachable. |
Only running accrues compute charges. An unreachable sandbox can still reserve CPU, memory, and disk on its host.
Host unavailable
unreachable means that the host does not respond after a grace period of about three minutes.
The sandbox retains its disk and placement. It is not terminal, and no timer changes it to failed.
Compute charges pause while it is unreachable. Disk charges continue as they do for a paused sandbox.
Allocated capacity still includes its CPU, memory, and disk because the VM can remain alive.
SSH, VNC, and preview connections still attempt access. Pause, resize, exec, process, and snapshot requests return a state error.
Delete completes at once and revokes its egress configuration and secret access.
Delete first removes the ingress route. If that step fails, Delete returns an error and leaves the sandbox available for retry.
If the delete cannot commit, the platform restores the route before it returns the error.
If the VM survives, the host removes it when the host returns.
If the host returns with the VM alive, the sandbox returns to running automatically.
If the host returns without the VM, the sandbox enters failed with reason vm_not_found.
An operator removal of the host also fails the sandbox, with reason node_removed.
Auto-pause and the maximum-run deadline do not act during the outage. Recovery preserves the original run deadline.
Hibernated and suspended sandboxes retain their state because their pause artifacts remain in durable storage.
If an operator removes the host before the pause artifacts reach durable storage, the paused sandbox fails with reason node_removed.
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. tektona sandbox resume --discard-memory starts it from its disk instead; that resume uses reason discard_memory_requested. |
suspended | Paused and resumable. An unexpected VM crash uses reason crashed. An incomplete memory snapshot uses reason partial_memory_image. |
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 sandbox workload failed, or the sandbox failed to start, pause, reboot, or receive a host. It cannot resume. |
A failed sandbox tells you why. tektona sandbox get shows an Error line, and the console shows the error on the sandbox page.
The API returns error.reason and error.at, the error timestamp in RFC 3339 format.
It also returns error.message for start_failed and disk_too_small.
Other errors show only the reason and the time, because their messages can name internal systems.
Error reasons
The API defines state and error.reason as enums. The SDK uses these values as typed unions.
History fields from_state and to_state remain strings because old states can appear there.
The former paused state appears only in history. Current paused sandboxes use hibernated or suspended.
| Reason | Meaning | Message shown |
|---|---|---|
scheduling_failed | The platform failed to assign or prepare a host. | No |
disk_too_small | The requested disk cannot hold the image. | Yes |
boot_failed | The VM failed to boot. | No |
create_timeout | The create request exceeded its deadline. | No |
no_capacity | No host has enough free resources. | No |
queue_wait_expired | The sandbox exceeded its wait for free resources. | No |
no_node_can_ever_fit | The request exceeds the resources of every host. | No |
invalid_placement | The host cannot read the sandbox placement. | No |
start_timeout | The sandbox failed to start before its deadline. | No |
start_failed | The sandbox image cannot start its program. | Yes |
reboot_failed | The sandbox failed to reboot. | No |
resume_stop_failed | The VM did not stop after a failed resume. The sandbox retains its disk. | No |
fork_schedule_request_failed | The platform failed to prepare, send, or save the fork placement. | No |
fork_schedule_response_decode_failed | The platform cannot read the scheduler response for a fork. | No |
fork_scheduler_error | The scheduler refused the fork. | No |
fork_egress_inherit_failed | The fork failed to copy the parent network configuration. | No |
invalid_command | The host cannot read or accept the pause request. | No |
pause_unknown | The host cannot determine the VM state after a pause failure. | No |
pause_record_unreadable | The host cannot read the saved pause result. | No |
pending_snapshot_dropped | The platform discarded a pending image snapshot from an older sandbox. | No |
unknown | The stored error reason is outside the current reason list. | No |
runner_unreachable | The sandbox host does not respond. The sandbox can recover when the host returns. | No |
vm_not_found | The host returned without the sandbox VM. | No |
node_removed | An operator removed the host. | No |
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
A suspended or hibernated sandbox shows a red crashed badge when its reason is crashed, start_failed, or start_timeout.
The badge also stays red while the sandbox has an error, even after a refused resume request.
Other paused sandboxes keep the yellow badge.
The underlying state stays resumable.
The details page shows an error banner with the reason, public message when present, and timestamp.
A plain crash without an error has no banner.
The Resume button stays in the page header.
tektona sandbox get shows the state as suspended (crashed: crashed) for a plain crash.
- Running counts only
runningsandboxes. - Paused counts
hibernated+suspended(so a crash-suspended sandbox shows here). failed,deleting, anddeletedare hidden from the dashboard sandbox list by default. Tick Show deleted & errored to include them.tektona sandbox lshides less: onlydeletinganddeleted.- Allocated now includes CPU, memory, and disk for unreachable sandboxes. The host can still hold those resources.
- Usage per day charts stop compute accrual while a sandbox is
unreachable. Disk accrual continues as it does during a pause.
Where states are recorded
Every transition is written to the sandbox's history with a timestamp, a
reason (for example idle_timeout, crashed, user_resume), and the actor
that caused it. You can review it per sandbox in the detail view.
The API history also returns an error field on each transition that records an error.
A refused resume request appears there without replacing the sandbox error.
Historical transitions can still show the former error state.
The API returns state_reason on sandbox details and list items.
This nullable string records the reason for the transition into the current state.
A completed pause uses pause_completed.
After a refused resume, state_reason describes that request while error preserves the earlier sandbox failure.
Watch state changes
To follow a sandbox and not poll it, open its event stream:
curl -N -H "Authorization: Bearer $TEKTONA_API_KEY" \
https://api-dev.tektona.ai/v1/sandboxes/$SANDBOX_ID/eventsThe stream uses server-sent events. A sandbox event carries the sandbox with the same body as GET /v1/sandboxes/{id}. The stream sends it at once, then again each time a field changes, such as the state, the tags or the error.
A removed event says that no more events come for the sandbox. Its reason is deleted, not_found or forbidden. Close the stream after the last removed event: a browser EventSource opens a closed stream again by itself. A ping event arrives every 25 seconds when nothing else does.
To follow several sandboxes on one connection, use GET /v1/sandbox-events and repeat the id parameter, up to 100 times.