Manage Sandboxes

A sandbox is an isolated VM that starts from a template. Every sandbox runs in a single org / project. Set yours with tektona ctx before continuing.

Create

tektona sandbox create go-dev
tektona sandbox create tektona/desktop --egress-network-policy tektona/open

The positional argument is a template reference: go-dev, go-dev:stable, org/go-dev, or tektona/sandbox-base. It is required. To start from an OCI image of your own, build a template from it with tektona template create.

A template supplies the CPU, memory, disk and environment the sandbox starts with. The flags below override those, one field at a time.

Aliases: tektona s c. Flags:

A larger example:

tektona s c tektona/desktop \
  --cpu 1 --memory 4 --disk 20 \
  --egress-policy tektona/open \
  --ssh

Choosing a template

Tektona provides two templates, so a new project starts a sandbox with no setup:

tektona/desktop is the template used throughout these docs. See Official Images for everything both of them include.

tektona s c tektona/desktop --egress-policy tektona/open --vnc --browser

To start from an image of your own, build a template from it first:

tektona template create my-app --image ghcr.io/acme/my-app:1.4.0
tektona sandbox create my-app

See Templates for the manifest and the build commands, and Run a Custom Image for private registries.

Pinning a version

Each build of a template mints a version, and a tag points at one version. A reference with no tag resolves the default tag, and that tag moves as new versions arrive. Name a tag, or pin the version id, to get the same start every time.

# the default tag — it moves, so a later create can start from a newer version
tektona s c tektona/desktop

# another tag
tektona s c go-dev:stable

# an exact version — deterministic, and it ignores the tag
tektona s c go-dev --template-version 01M25RVHMYFX9TMQ2BHN4NCHD9

tektona template version ls <template> lists a template's versions, newest first. A sandbox also reports the exact version it started from, so the answer stays true after the tag moves.

Wait

tektona sandbox create waits for the API's initial wait=true attempt. That API wait is bounded, so image builds can still be in progress when the command returns. To block until the sandbox reaches a target state:

tektona sandbox wait <sandbox-id>

Defaults: --state running, --timeout 10m, polling every 2 seconds. Override any of them:

tektona sandbox wait <id> --state running --timeout 3m
tektona sandbox wait <id> --state paused                  # matches hibernated or suspended
tektona sandbox wait <id> --state hibernated              # exact pause mode
tektona sandbox wait <id> --interval 1s                   # tighter polling
tektona sandbox wait <id> -o json                         # { id, state, elapsed_ms }

There is no literal paused state. pause settles a sandbox into hibernated (default --mode hibernate) or suspended (--mode suspend). --state paused is a convenience target that matches either real paused state, so pause && wait --state paused works regardless of mode. Pass --state hibernated or --state suspended to wait for a specific mode.

wait exits 0 when the target state is reached, non-zero on timeout, and fails fast if the sandbox enters a terminal state (error, deleted, deleting, failed) while waiting for a non-terminal target, so scripts don't hang on broken images.

If you pass --ssh or --vnc to create, the CLI attempts to open that connection after the sandbox create response is returned.

List

tektona sandbox ls               # every sandbox you still have
tektona sandbox ls --include-deleted   # add the ones whose delete has started or finished
tektona sandbox ls --wide        # full image digests + resource columns
tektona sandbox ls --state running
tektona sandbox ls --template go-dev
tektona sandbox ls --template-version 01M25RVHMYFX9TMQ2BHN4NCHD9
tektona sandbox ls -o json

--template shows the sandboxes built from one template, whichever version each one holds. It takes a reference, the same form a create takes: go-dev, project/go-dev, org/base-ubuntu or tektona/sandbox-base. Name a template that does not exist and the command says so, rather than showing an empty list.

--template-version shows the sandboxes built from one version. A version delete names the version it refuses on, so this is how you list the sandboxes that record it.

The two are alternatives, because a version already names its template. A tag belongs on neither: a tag moves between versions, so pass the version it points at to --template-version.

This command shows only the sandboxes you can see. To list every owner's, use tektona admin sandbox ls --template-version <id>.

Neither command reproduces the refusal's set exactly. The refusal counts a sandbox until its teardown finishes, and a list hides a sandbox from the moment its delete is requested. --include-deleted shows those, and also shows sandboxes whose delete finished, which no longer block.

Inspect

tektona sandbox get <sandbox-id>            # aliases: info, show, details
tektona sandbox get <sandbox-id> -o json

Fork

Create a point-in-time copy of a sandbox. The source keeps running.

tektona sandbox fork <sandbox-id>                    # filesystem fork (fast)
tektona sandbox fork <sandbox-id> --mode full        # memory + disk (running only)
tektona sandbox fork <sandbox-id> --ssh              # SSH into the fork

Flags: --mode filesystem|full, --ssh, --vnc, --vnc-type, -b, --browser.

--mode full requires a running sandbox (it captures live memory). To full-fork a paused (hibernated or suspended) sandbox, resume it first. A filesystem fork works for paused sandboxes.

Pause / resume

tektona sandbox pause <sandbox-id>                   # hibernate (default)
tektona sandbox pause <sandbox-id> --mode suspend
tektona sandbox resume <sandbox-id>

Modes: hibernate saves the sandbox's memory, so running processes are still there when you resume. suspend saves only the disk, so resuming boots the sandbox fresh and processes do not survive.

Lifecycle

Change auto-pause / auto-delete timers on an existing sandbox. To view the effective settings and where each is inherited from, run tektona sandbox get <sandbox-id>:

tektona sandbox lifecycle <sandbox-id> --auto-pause 15m
tektona sandbox lifecycle <sandbox-id> --auto-delete 30d
tektona sandbox lifecycle <sandbox-id> --auto-pause-mode suspend
tektona sandbox lifecycle <sandbox-id> --no-auto-resume

You can also set these at create time with the same flags — create takes --auto-pause, --auto-pause-mode, --auto-resume, and --auto-delete. Any flag you omit inherits the project/platform default:

tektona sandbox create tektona/sandbox-base --auto-pause 30m --auto-pause-mode suspend
tektona sandbox create tektona/sandbox-base --auto-pause never --auto-delete 7d

Resize

Change a sandbox's CPU, memory, or disk after creation:

tektona sandbox resize <id> [--cpu N] [--memory N] [--disk N] [--force]

Only the flags you pass change, and omitted values are kept. The command prints the shape before and after.

tektona sandbox resize sbx_123 --cpu 4 --memory 8     # scale up
tektona sandbox resize sbx_123 --disk 20              # grow the disk
tektona sandbox resize sbx_123 --memory 2 --force     # shrink memory

The new shape is persisted and applied on the next start or resume. It is not hot-plugged into a running VM, so pause/resume (or stop/start) the sandbox for it to take effect. Disk can only grow, and shrinking memory requires --force. Live CPU/memory hot-plug and online disk growth are planned follow-ups.

Screenshot

tektona sandbox screenshot <sandbox-id>                  # saves the file
tektona sandbox screenshot <sandbox-id> -o capture.png
tektona sandbox screenshot <sandbox-id> --open           # also open it in an image viewer

Alias: tektona s ss.

Desktop control

tektona sandbox desktop start <sandbox-id>
tektona sandbox desktop stop <sandbox-id>
tektona sandbox desktop status <sandbox-id>            # prints active or inactive
tektona sandbox desktop status <sandbox-id> -o json

Delete

tektona sandbox rm <sandbox-id>
tektona sandbox rm <sandbox-id> --yes              # skip confirmation
tektona sandbox rm --all --yes                     # every sandbox in the current context

Aliases: tektona s d, tektona s rm.