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. A PATH change 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 and pip install --user put them for the tektona user, is on the PATH, 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 tektona user 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 --vnc

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

TemplateWhat it starts
tektona/sandbox-baseThe headless image above
tektona/desktopThe 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.

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-tools
tektona template build run -f my-desktop.template.tektona.yaml --tag default
tektona sandbox create my-desktop

Each 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-tools
tektona template create my-desktop --image ghcr.io/acme/my-desktop:1.0.0
tektona sandbox create my-desktop

See Templates for using your own image, and Container Registries for a private one.

On this page