Manage Sandboxes
Manage sandboxes from the shell.
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/openThe 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.
Sandbox names
Use --name to give a sandbox an optional name. Use lowercase letters, digits, and hyphens, up to 40 characters.
The name must not look like a ULID. Each live sandbox in a project needs a distinct name.
tektona sandbox create go-dev --name api-test
tektona ssh api-test
tektona sandbox rename api-test api-review
tektona sandbox ls --name api-review
tektona sandbox rename api-review --clearA 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:
| Flag | Default | Purpose |
|---|---|---|
--template-version | (none) | Pin an exact template version, ignoring the tag |
--name | (none) | Optional sandbox name |
--cpu | the template's, or 2 | CPU cores, up to the limit |
--memory | the template's, or 2 | Memory in GiB, up to the limit |
--disk | the template's, or 10 | Total root disk in GiB, from 10 up to the limit. Must be at least the image size, and a smaller value is rejected. |
--env | (none) | Environment variable (KEY=VAL, repeatable) |
--tag | (none) | Sandbox tag (repeatable) |
--user | the template's, or the image's USER | User the sandbox runs as, by name or uid. A name must exist in the image. |
--workdir | the template's, or the image's WORKDIR | Absolute directory the sandbox starts in. The sandbox creates it when it does not exist. |
--region | the region of the installation | Region ID, for example fr-par-1. The CLI never asks for it. |
--egress-network-policy | settings default | Egress network policy (tektona/dev, tektona/open, …) |
--egress-proxy-profile | (none) | Egress proxy profile (org/<name>, project/<name>, or <name>) |
--public | false | Expose preview URLs without a token |
--share | Share the sandbox with the project: use lets members operate it, manage also lets them delete it. Default: private | |
--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) |
A larger example:
tektona s c tektona/desktop \
--cpu 1 --memory 4 --disk 20 \
--egress-network-policy tektona/open \
--sshChoosing a template
Tektona provides two templates, so a new project starts a sandbox with no setup:
| Template | What it starts |
|---|---|
tektona/sandbox-base | The headless image: Ubuntu with systemd, a developer toolchain, Node.js and AI coding agents |
tektona/desktop | The same, plus an X11 desktop and Chrome, for VNC and computer use |
tektona/desktop is the template used throughout these docs. See
System Templates and Images for everything both of them include.
tektona s c tektona/desktop --egress-network-policy tektona/open --vnc --browserTo 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-appSee the template CLI reference for the manifest and the build commands, and Container Registries for private images.
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 01M25RVHMYFX9TMQ2BHN4NCHD9tektona 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 until the sandbox runs or fails, for up to 10
minutes. When the command shows the sandbox ID, press Ctrl+C to stop the wait.
The sandbox continues to start. To
block until a 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 (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 # image, owner, tags, proxy profile, and 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 jsonThe Sandbox section shows ID, state, template, and resources.
Template shows the tag and version. Metadata shows the project, region, creation time, and tags.
Automatic actions describes when the sandbox pauses, resumes, or deletes itself.
Permissions shows the owner, share type, and sandbox access level with the API values.
Use --output json to inspect the project role and configuration sources.
The default list starts with ID, state,
template, and age columns. Use --wide to see the image, tags, owner, egress proxy profile, and resources.
The TAGS column puts three tags on each line. For scripts, use -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 forkFlags: --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>
tektona sandbox resume <sandbox-id> --discard-memoryModes: 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.
A hibernated sandbox resumes with its memory only on a runner node whose CPU
can restore it. When the resume fails with a no-capacity error, the sandbox
keeps its memory. --discard-memory starts a hibernated sandbox from its disk
instead, on any node with room: its running processes and memory contents are
lost. The command asks for confirmation. Without a terminal, or with
--output json or --no-input, add --yes.
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-resumeYou 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 7dResource limits
Each installation sets the largest CPU, memory and disk that one sandbox may ask for. A new installation starts at 16 cores, 32 GiB of memory and 25 GiB of disk. Show the current limits:
tektona sandbox limits
tektona sandbox limits -o json- A value outside the limits is refused with the field that is outside them. It is not reduced to fit.
- A new sandbox needs at least 10 GiB of disk.
- When neither the create nor the template sets a value, the sandbox gets 2 cores, 2 GiB and 10 GiB. A limit below that value reduces it.
- A template default above the limit is refused too. Pass a value that fits,
for example
--disk 20. - A sandbox above a lowered limit keeps running, pausing and resuming. A fork of it gets the same size.
Resize
Change a sandbox's CPU, memory, or disk after creation:
tektona sandbox resize <id> [--cpu N] [--memory N] [--disk N] [--force] [--mode live|deferred] [--reboot]| 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 |
--mode | live: apply CPU and memory now, or fail. deferred: apply them on the next reboot. Default: live when the sandbox supports it, else the next reboot |
--reboot | Reboot the sandbox after a CPU or memory change that waits for a reboot. Asks first unless you pass --yes |
A value that grows is held to the limits. A value that stays or shrinks is not, so a sandbox above a lowered limit can still shrink its CPU and memory.
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 --cpu 4 --mode live # now, or fail
tektona sandbox resize sbx_123 --disk 20 # grow the disk
tektona sandbox resize sbx_123 --memory 2 --force --reboot # shrink memory, then rebootA disk grow applies at once. On a running sandbox the guest sees the new space when the command returns.
CPU and memory grow live on a running sandbox that supports it. When a live grow is not possible, the change waits for the next reboot, and the command says why: for example, the node has no free capacity. A pause and resume does not apply a waiting change. A shrink always waits for the next reboot.
With --mode live, a change that cannot apply now fails, and CPU and
memory do not change. A disk that grew before the failure keeps its new
size. The error names the cause, for example (no_capacity) or
(shrink_unsupported). If the platform cannot tell whether the change
applied (live_resize_unknown), the change waits for the next reboot.
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 viewerAlias: 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 jsonDelete
tektona sandbox rm <sandbox-id>
tektona sandbox rm <sandbox-id> --yes # skip confirmation
tektona sandbox rm --all --yes # every sandbox in the current contextAliases: tektona s d, tektona s rm.