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:

StateMeaning
creatingThe request was accepted and the sandbox record exists.
schedulingThe platform is placing the sandbox on a host.
queuedNo host can accept the sandbox now. The sandbox waits for capacity.
startingThe 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

StateMeaning
runningThe 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.

StateMeaning
hibernatedPaused 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.
suspendedPaused 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.

StateMeaning
failedThe 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.

ReasonMeaningMessage shown
scheduling_failedThe platform failed to assign or prepare a host.No
disk_too_smallThe requested disk cannot hold the image.Yes
boot_failedThe VM failed to boot.No
create_timeoutThe create request exceeded its deadline.No
no_capacityNo host has enough free resources.No
queue_wait_expiredThe sandbox exceeded its wait for free resources.No
no_node_can_ever_fitThe request exceeds the resources of every host.No
invalid_placementThe host cannot read the sandbox placement.No
start_timeoutThe sandbox failed to start before its deadline.No
start_failedThe sandbox image cannot start its program.Yes
reboot_failedThe sandbox failed to reboot.No
resume_stop_failedThe VM did not stop after a failed resume. The sandbox retains its disk.No
fork_schedule_request_failedThe platform failed to prepare, send, or save the fork placement.No
fork_schedule_response_decode_failedThe platform cannot read the scheduler response for a fork.No
fork_scheduler_errorThe scheduler refused the fork.No
fork_egress_inherit_failedThe fork failed to copy the parent network configuration.No
invalid_commandThe host cannot read or accept the pause request.No
pause_unknownThe host cannot determine the VM state after a pause failure.No
pause_record_unreadableThe host cannot read the saved pause result.No
pending_snapshot_droppedThe platform discarded a pending image snapshot from an older sandbox.No
unknownThe stored error reason is outside the current reason list.No
runner_unreachableThe sandbox host does not respond. The sandbox can recover when the host returns.No
vm_not_foundThe host returned without the sandbox VM.No
node_removedAn operator removed the host.No

Removal

StateMeaning
deletingTeardown is in progress, and the sandbox is being removed from its host.
deletedFully 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 running sandboxes.
  • Paused counts hibernated + suspended (so a crash-suspended sandbox shows here).
  • failed, deleting, and deleted are hidden from the dashboard sandbox list by default. Tick Show deleted & errored to include them. tektona sandbox ls hides less: only deleting and deleted.
  • 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/events

The 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.

On this page