Tektona Docs

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

Create

tektona sandbox create --image ghcr.io/tektona-ai/desktop-x11:0.4.3 --egress-policy tektona/open

Aliases: tektona s c. Flags:

Flag	Default	Purpose
`-i, --image`	(required)	OCI image reference
`--cpu`	`2`	CPU cores (1 to 16)
`--memory`	`2`	Memory in GiB (1 to 32)
`--disk`	`10`	Total root disk in GiB (1 to 25). Must be at least the image size, and a smaller value is rejected.
`--env`	(none)	Environment variable (`KEY=VAL`, repeatable)
`--location`	`default`	Sandbox location
`--egress-policy`	settings default	Egress network policy (`tektona/dev`, `tektona/open`, …)
`--public`	`false`	Expose preview URLs without a token
`--auto-pause`	inherit	Idle timeout: a duration (`15m`), `never`, or `inherit`
`--auto-pause-mode`	inherit	Pause mode: `hibernate`, `suspend`, or `inherit`
`--auto-resume`	inherit	Wake on activity: `true`, `false`, or `inherit`
`--auto-delete`	inherit	Delete TTL: a duration (`30d`), `never`, or `inherit`
`--ssh`	`false`	Open SSH after creation
`--vnc`	`false`	Start VNC after creation
`--vnc-type`	`web`	VNC client (`web`)
`-b, --browser`	`false`	Open the browser automatically (with `--vnc`)
`-v, --verbose`	`false`	Print the trace ID for debugging

A larger example:

tektona s c \
  --image ghcr.io/tektona-ai/desktop-x11:0.4.3 \
  --cpu 1 --memory 4 --disk 20 \
  --egress-policy tektona/open \
  --ssh

Choosing an image

Any OCI image works. Tektona pulls it from the registry the first time you reference it and caches it as a snapshot for subsequent boots.

Tektona ships an official X11 desktop image, ghcr.io/tektona-ai/desktop-x11. It's the recommended starting point and the image used throughout these docs: it ships an X session, a ready-to-run Chrome browser, the in-sandbox tektonactl tool, and the libraries the desktop, VNC, and tektonactl desktop workflows need. See Official Images for everything included, and for the headless sandbox-base variant.

tektona s c --image ghcr.io/tektona-ai/desktop-x11:0.4.3 --egress-policy tektona/open --vnc --browser

Image references must be deterministic: a non-latest tag, a @sha256:... digest, or both. The only forms Tektona rejects are the ones that float over time: a bare image with no tag or digest, and a bare :latest without a digest pin.

# ✓ versioned tag (recommended for human-readability)
tektona s c -i ghcr.io/tektona-ai/desktop-x11:0.4.3

# ✓ versioned tag pinned to an exact build
tektona s c -i ghcr.io/tektona-ai/desktop-x11:0.4.3@sha256:<digest>

# ✓ digest only — fully deterministic, OCI-standard
tektona s c -i ghcr.io/tektona-ai/desktop-x11@sha256:<digest>

# ✓ :latest is allowed when pinned by digest
tektona s c -i ghcr.io/tektona-ai/desktop-x11:latest@sha256:<digest>

# ✗ bare :latest — rejected (floats)
tektona s c -i ghcr.io/tektona-ai/desktop-x11:latest

# ✗ no tag and no digest — rejected
tektona s c -i ghcr.io/tektona-ai/desktop-x11

Browse all published versions on ghcr.io/tektona-ai/desktop-x11 and pick the highest-numbered tag, or copy a digest if you want to lock to an exact build.

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 5m, 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, completed) 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               # default state filter
tektona sandbox ls --all         # include terminated
tektona sandbox ls --wide        # full image digests + resource columns
tektona sandbox ls --state running
tektona sandbox ls -o json

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        # full snapshot (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 keeps the page cache cold and frees more memory. suspend keeps RAM warm for faster resume.

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 --image ubuntu:24.04 --auto-pause 30m --auto-pause-mode suspend
tektona sandbox create --image ubuntu:24.04 --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]

Flag	Purpose
`--cpu`	New vCPU count
`--memory`	New memory, in GiB
`--disk`	New disk size, in GiB (grow-only)
`--force`	Required to shrink memory below its current value

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>                  # opens the file
tektona sandbox screenshot <sandbox-id> -o capture.png
tektona sandbox screenshot <sandbox-id> --no-open

Alias: tektona s ss.

Desktop control

tektona sandbox desktop start <sandbox-id>
tektona sandbox desktop stop <sandbox-id>

Delete

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

Aliases: tektona s d, tektona s rm.

Manage Sandboxes