System Templates and Images
What ships in Tektona's system templates and images, and how to extend them.
Tektona publishes two official sandbox images on GitHub Container Registry.
Both are built on the current Ubuntu LTS (26.04) and boot with systemd. The
default tag moves to a newer LTS when one ships. A sandbox
behaves like a regular Linux machine: apt install nginx starts and enables
the service, systemctl works, and background daemons keep running
(requires image 0.5.0 or later).
sandbox-base
ghcr.io/tektona-ai/sandbox-base
is the headless image — pick it for agent, CI-style, or server workloads
that don't need a screen. It ships:
- AI coding agents: Claude Code, Codex, and opencode, ready on the
PATH(each release bundles the latest stable versions). - For a custom image that does not include opencode, install it in a template
build step into a directory on the default
PATH, such as/usr/local/bin. AgentLink starts it without a login shell. APATHchange in a shell profile does not reach agent-runtime. The runner does not add opencode to the guest. - Node.js 22 LTS with npm.
- A developer toolchain: git (with LFS), Python 3 with pip, build-essential, cmake, and the usual command-line tools for building, inspecting, and debugging (curl, jq, yq, rsync, htop, strace, and more).
- pipx for Python CLIs.
/home/tektona/.local/bin, where pipx andpip install --userput them for thetektonauser, is on thePATH,tektona ssh <id> -- <command>included. - Man pages, ffmpeg, and UTF-8 locales for English, German, Spanish, French and
Portuguese (
LANG=en_US.UTF-8). - The
tektonauser with passwordless sudo; sessions land in/home/tektona.
desktop-x11
ghcr.io/tektona-ai/desktop-x11
is sandbox-base plus a full X11 desktop, and the recommended starting point
for VNC and computer use. On top of
everything above it adds:
- A lightweight desktop environment (Openbox window manager with a dock), viewable in the browser or any VNC client.
- Google Chrome, preconfigured to run inside the sandbox with no first-run prompts — ready for AI browser automation.
- Desktop apps: a terminal, file manager, text editors, calculator, PDF viewer, and LibreOffice Writer and Calc.
- The tooling behind
tektonactl desktop— screenshots, clicking, typing, window management, and screen recording.
tektona sandbox create tektona/desktop --vncTemplates Tektona provides
A sandbox starts from a template, never from an image reference. Both images
ship as templates, so you can start a sandbox with no setup. A template
reference that begins with tektona/ is one Tektona maintains — you can read
it, and only Tektona changes it.
| Template | What it starts |
|---|---|
tektona/sandbox-base | The headless image above |
tektona/desktop | The desktop image above |
Leave the tag off and you get :default, which always points at the
version Tektona currently recommends:
POST /v1/sandboxes
{ "template": "tektona/sandbox-base" }A template version supplies defaults, never fixed values, so anything the
create sets wins. The sandbox records the exact version it started from, so
the answer stays true after :default moves on.
To pin a version, use the version id the sandbox reports. To build your own starting point, create a template in your project.
Versions
Images are versioned together and tagged X.Y.Z (plus a floating X.Y).
Browse published versions on the package pages linked above and use the
highest-numbered tag when you build a template from one. To pin what a sandbox
starts from, see
Choosing a template.
Extending
There are two ways to add your own tools to an official image.
With a template (recommended)
A template adds build steps on top of an official image. Tektona runs the steps and stores the result. You need no Dockerfile, no image build and no registry of your own:
# my-desktop.template.tektona.yaml
apiVersion: tektona.ai/v1
kind: SandboxTemplate
metadata:
name: my-desktop
spec:
build:
image: ghcr.io/tektona-ai/desktop-x11:0.7.1
steps:
- name: install tools
run: |
apt-get update
apt-get install -y your-toolstektona template build run -f my-desktop.template.tektona.yaml --tag default
tektona sandbox create my-desktopEach build makes a new version of the template, with its own build log. A template also sets the default size, env, user and working directory of each sandbox made from it. See Templates for the manifest, versions and tags.
With a Dockerfile
Both images are ordinary OCI images. Use a Dockerfile when you already build images in CI, or when the same image also runs outside Tektona. Push the result to a registry, then build a template from it:
FROM ghcr.io/tektona-ai/desktop-x11:0.7.1
RUN apt-get update && apt-get install -y your-toolstektona template create my-desktop --image ghcr.io/acme/my-desktop:1.0.0
tektona sandbox create my-desktopSee Templates for using your own image, and Container Registries for a private one.