Templates

Install the tools of your project once, and start every sandbox with them ready.

Every Tektona sandbox starts from a template. A template is a base image, the commands that install your tools, and the defaults of a sandbox: CPU, memory, disk, environment variables, user and working directory.

Tektona runs the commands for you, on top of the base image. So most projects need no image of their own, no Dockerfile and no registry.

Before you start

  • The tektona CLI installed and configured (tektona login), with an org/project context set (tektona ctx show).

Build a template for your project

This tutorial builds a template for a Go project. Every sandbox from it starts with Go and make installed.

Write the manifest

A manifest is a file that describes the template. Write a starter:

tektona template init go-dev

This writes go-dev.template.tektona.yaml. Edit it so that it installs your tools:

apiVersion: tektona.ai/v1
kind: SandboxTemplate
metadata:
  name: go-dev
spec:
  build:
    image: ghcr.io/tektona-ai/sandbox-base:0.7.1
    user: root
    steps:
      - name: install the tools
        run: |
          apt-get update
          apt-get install -y golang-go make

spec.build.image is the base image. Start from one of Tektona's official images, so that your steps install only what your project adds:

  • sandbox-base holds common developer tools.
  • desktop-x11 adds a desktop and Google Chrome, for browser tests and computer use.

Read System Templates and Images for the full list.

Each entry under steps is one command that installs what your project needs.

Commit the file beside your code, so that the team builds the same template.

Build the template

tektona template build run --file go-dev.template.tektona.yaml --tag default

Tektona starts a sandbox from the base image, runs the steps in order, and saves the result as a version. The command shows the build log while it runs. --tag default points the default tag at the new version.

Start a sandbox

tektona sandbox create go-dev --ssh

The name go-dev resolves the default tag. In the session, go version shows that the tools are there.

A create can override the defaults of the template, one field at a time. tektona sandbox create go-dev --cpu 8 keeps the memory and the disk of the template.

Change the template

Add a step to the manifest, for example to install a linter. Then build again:

tektona template build run --file go-dev.template.tektona.yaml --tag default

The build makes a new version, and default moves to it. New sandboxes start from the new version. Running sandboxes keep the version that they started from.

How templates, versions and tags relate

A template holds many versions. Each build adds one version. A tag is a movable pointer to one version of its template. A sandbox starts from one version.

Versions

Each build of a template makes a version. A version never changes. It holds the image it was built from, its own build log, and the defaults of a sandbox.

Three things follow from that:

  • A rebuild changes no running sandbox. Each sandbox records the exact version it started from. That answer stays true after a newer version arrives.
  • Two versions of one template differ. One gives 4 cores, the next gives 8. A pinned version fixes the size too.
  • A failed build publishes nothing. The build stops at the first step that fails. No half-installed version reaches your sandboxes.

A new name or a new description of a template costs no build. A new image, a new step or a new default needs one.

Tags

A tag is a movable pointer to one version. A reference with no tag resolves the default tag:

tektona sandbox create go-dev          # the default tag
tektona sandbox create go-dev:stable   # another tag

A build moves the tag that you name:

tektona template build run go-dev --tag stable

A build with no --tag moves no tag. Build first, test the version, then move the tag onto it. To go back, move the tag onto an older version.

For the same start every time, name a tag that you never move, or pin the version id:

tektona sandbox create go-dev --template-version 01JABCDEF0123456789ABCDEFG

A tag also keeps a version safe from the retention rules below.

References and scope

A template reference names a scope and a template:

ReferenceWhat it means
go-devA template in your current project
project/go-devThe same thing, written out
org/go-devA template your organization owns
tektona/sandbox-baseA template Tektona provides

Add :<tag> to any of these forms.

The scope comes from your CLI context, which tektona ctx show prints. A manifest file carries no org and no project, so one file works in every project.

Tektona provides tektona/sandbox-base and tektona/desktop. Read System Templates and Images for what each one holds.

Retention

Tektona clears template versions that nobody uses. It archives a version that no sandbox used for 2 days, and it deletes that version 1 day later. An organization or project can change both windows. A tag exempts a version from both rules.

Read Template Version Lifecycle for the full rules, the labels that tell you what comes next, and how to get an archived version back.

Permissions

To use a template, you need the project Writer role. That role creates sandboxes, and it starts them from the project's templates, the organization's templates and Tektona's.

To manage a template, you need a role that the scope of the template decides:

ScopeWho reads itWho builds and manages it
project/…project Readerproject Admin
org/…organization Memberorganization Admin
tektona/…anyoneTektona only

Management covers create, build, update, tag, archive and delete. Templates have no middle role: a project Writer creates sandboxes, but builds no template.

Read Roles & Permissions for the roles themselves.

Write build steps

This section gives the rules for the steps in a manifest. The template CLI reference lists every key of the manifest.

Each step has a name and a run script. The name is the title of the step in the build log. It has 1 to 80 characters, no line breaks, and no space at the start or the end. Each step in a build needs a different name.

The steps run in the order you write them. The build stops at the first step that fails, and the build fails with it. The build then publishes no version, as Versions describes. tektona template build logs <build-id> shows the script and the output of each step.

A build log keeps the first 4 MiB of output of all steps together. Past that, the build continues, and the log ends with a line that says how many bytes of output were dropped.

A script stops at its first failed line, and the step reports the exit code of that line. The script runs as bash -eo pipefail -c, or as sh -e -c when the image has no bash. Set spec.build.shell to use a different shell. For example, shell: /bin/sh -e -x -c also prints each line before it runs.

With bash, a failed command in a pipe also fails the step. So cmd | head can fail when head exits before cmd writes all of its output. Add || true to such a line when a partial read is what you want.

The image's entrypoint during a build

Your steps run without the image's ENTRYPOINT or CMD. A service in the base image, such as nginx, is not up while your steps run, and it writes nothing into the version. Do not call the service from a step. Start what a step needs in that step.

An init system in the image, such as systemd, does run. So a step that installs a package with a service, for example apt-get install nginx, enables the unit the usual way.

What carries over between steps

All steps run in one build sandbox, in order. Each step is its own process.

A step changes…The next step sees itA sandbox made from the version sees it
files (installed packages, config, anything on disk)yesyes: the disk is what the version captures
export FOO=barno: each step is its own processno
cd /dirno: each step starts in its workdirno
spec.build.envyes, every stepno: use spec.sandbox.env for a sandbox

A step does not start a login shell. So /etc/profile.d/ and /etc/environment do not reach the next step. To use a tool that an earlier step installed, call it by its absolute path, or set the full PATH in spec.build.env. For example, a step installs Go into /usr/local/go. The next step then runs /usr/local/go/bin/go, or spec.build.env sets PATH to /usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin.

A step cannot pass a value to the next step, other than through a file.

user, workdir and env under spec.build apply to the steps. The same three keys under spec.sandbox apply to sandboxes made from the version, and the two are set separately. A step can override user and workdir for itself.

spec.sandbox.user and spec.sandbox.workdir replace the image's own USER and WORKDIR for the workload, SSH sessions, file copies and the desktop. A create with --user or --workdir replaces them in turn, one field at a time. A user name must exist in the image, or the sandbox fails to start. tektona sandbox get then names the user in its Error line. A workdir that does not exist is created, owned by that user.

Name no user and the steps run as the image's own USER, in its WORKDIR. spec.sandbox does not reach the steps. So when spec.sandbox.user names another user, a file that a step writes belongs to the step's user, not to the sandbox's. Ubuntu and Alpine declare no user, so their steps run as root. An image that declares one needs user: root for apt-get and for anything else that installs packages, as the tutorial above has.

Start from your own image

Use your own image instead of build steps when one of these is true:

  • The result has to come from a Dockerfile that you commit.
  • You use the same image outside Tektona.
  • The install takes so long that you want to run it once in your own CI.

Pass the image with --image, and you need no manifest:

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

The first command creates the template, builds its first version, and waits for the build. That version takes the default tag. To rebuild from a newer image, and to move the tag onto what the build produces:

tektona template build run my-app --image ghcr.io/acme/my-app:1.5.0 --tag default

Image references follow the same rules as docker pull: an image with no tag and no digest means :latest. Pin the image by a @sha256:… digest, so that each build uses the same bytes.

A manifest can also name your image in spec.build.image and add steps on top.

A public image needs no setup. A private image needs a registry credential on your project. Read Container Registries to set one up. If a registry refuses a build, the error says whether this project has a matching registry. Check the named registry's token, or add a registry for the image host to this project. The build details can also name another project that you can read and that has a registry for the image. An organization template has no project registry. Use a public image or create the template in a project that has a matching registry.

What Tektona takes from your image

Tektona reads these values from the image and applies them to every sandbox that runs it.

Dockerfile instructionEffect
ENVSet in every SSH session, terminal and process.
WORKDIRThe directory where a session starts, and where a build command that names no workdir runs. Tektona falls back to $HOME.
ENTRYPOINT and CMDBy default, start at boot, even when the image has an init system.
USERThe user that runs ENTRYPOINT and CMD, your SSH sessions, the desktop session, and a build command that names no user.

Where a session starts, and what $HOME is

Two values decide this, and they are resolved separately.

The start directory is the first of these that exists in the image:

  1. the image WORKDIR
  2. $HOME

$HOME is the first of these that applies:

  1. the passwd home of the user you name with --user
  2. ENV HOME in the image
  3. the passwd home of the image USER
  4. /, when the image declares no passwd entry for its USER

A session opened with --user <uid> is the exception: a uid your image does not declare has no home to take, so that session gets no $HOME at all and starts where it is.

$HOME is therefore always set, unless you name a uid the image does not declare. A session starts in / only because $HOME resolved to / — which happens for an image built FROM scratch, or for a numeric USER with no /etc/passwd line. Those sessions are consistent, but every tool then writes its dotfiles into the root directory. Give the image a passwd entry, or set ENV HOME.

Make the start directory and $HOME the same directory

A remote tool assumes they are, because an SSH login always starts in the user's home. When they differ, a tool that creates a directory with ~ and then writes to a path relative to the session uses two different places. Editors that upload a server component do exactly that, and the upload fails with No such file or directory.

The reliable way is a WORKDIR that is the session user's home:

FROM ubuntu:24.04
RUN useradd --create-home --shell /bin/bash dev
USER dev
WORKDIR /home/dev

For an image that keeps a root session, naming the directory as the home also works:

FROM ubuntu:24.04
RUN mkdir -p /workspace
WORKDIR /workspace
ENV HOME=/workspace

ENV HOME works for a non-root USER too. A session that names another user with --user is the exception: it takes that user's own home, so the two directories differ again for that session.

An image with no WORKDIR needs nothing — the start directory falls back to $HOME, so the two agree already.

The rule holds for every way into the sandbox: an SSH session, a remote command and tektona sandbox cp all start in the same directory, and the desktop session writes its files into the same $HOME.

The session user

An SSH session runs as the image USER, the way sshd runs a login as the user that authenticated. This covers the shell, a remote command, and file transfer with tektona sandbox cp, so a file you upload belongs to the same user. An image with no USER line, or with USER root, keeps a root session.

USER also runs the ENTRYPOINT or CMD your image names. It does not run an init system Tektona starts for you: an image that names neither leaves Tektona to start the init system in the image, and that one runs as root, because an init system cannot run as a non-root process. So a non-root USER is safe to set on an image that ships systemd — the sandbox boots, and every session in it is still yours.

To use another user for one session, name it with --user:

tektona ssh 01JQXYZ123 --user root
tektona sandbox cp ./app.tar 01JQXYZ123:/opt/ --user root

--user takes a lowercase name from your image's passwd file, or a uid. A name your image does not have fails the session and says so. Names outside that shape — uppercase, longer than 32 characters — are refused before the connection opens.

A named user brings its own home directory: the session gets that user's HOME and starts there, even when your image sets ENV HOME to something else. Without --user the image's ENV HOME still wins.

The session also gets the groups the user belongs to, so a USER in your image's docker or sudo group keeps that access over SSH.

A USER your image cannot resolve falls back to root, because a sandbox that refuses every session is harder to repair than one that opens a root shell. A numeric USER with no passwd entry runs as that uid with its own group only, with HOME=/, so the session starts at /.

The login shell

An interactive session starts a login shell, so /etc/profile, /etc/profile.d/* and the user's own profile run. A remote command runs through the same shell with -c, which is not a login shell — the same rule ssh host -- cmd follows.

Put a PATH for your toolchain in /etc/profile.d/ and every interactive session has it. A login shell reads ~/.bash_profile, not ~/.bashrc, so an image that only appends to ~/.bashrc — what nvm install and conda init bash write — needs a ~/.bash_profile that sources it, the way a distro's own default does.

A USER whose passwd shell is nologin or false still gets a working shell. Those say "this account does not log in", which useradd -r assigns by default; honouring them would leave the sandbox with no way in at all.

Tektona also sets SSH_CONNECTION, SSH_CLIENT and — for a session with a terminal — SSH_TTY, the same values sshd exports. The addresses are your connection to Tektona, not to the sandbox.

Tektona sets SHELL, USER and LOGNAME for each session, because an editor picks the remote shell from SHELL. The value comes from the first source that supplies it:

  1. The --env flag on tektona sandbox create.
  2. An ENV SHELL line in your image.
  3. The passwd entry of the session user.

SHELL names the shell the session runs. If that source supplies nologin or false, SHELL names the working shell Tektona starts.

--user does not change this order. A named user brings its own HOME, USER and LOGNAME, but not its shell. A uid with no passwd entry brings none of them.

Most images need no change. Set ENV SHELL only to override the passwd entry. A SHELL your image does not ship fails the session with the error, the same as ssh to a host whose passwd names a missing shell.

A session whose home directory is missing still opens. It starts at / instead.

What a minimal image needs

A small image works, and a FROM scratch image with one static binary runs. What such an image supports depends on three things it may not ship.

Your workload does not have to stay alive — it only has to start. Tektona's init is the first process in the sandbox and keeps it running after your ENTRYPOINT exits. The CMD of ubuntu is /bin/bash, which exits at once with no terminal, and that sandbox stays usable.

Your image shipsWithout it
An ENTRYPOINT or CMDNothing runs in the sandbox, and it comes up anyway. Tektona's init starts no process of its own to stand in for yours, so a FROM scratch image with no entrypoint is a usable, empty sandbox.
A shell — /bin/sh, /bin/bash, or the one ENV SHELL namestektona ssh fails with login: exec /bin/sh: no such file or directory. A shell is the program a session starts.
An /etc/passwd fileA session still opens, but USER and LOGNAME are unset, it gets no supplementary groups, $HOME becomes /, and --user fails: look up user "dev": open /etc/passwd: no such file or directory.

File transfer needs none of them. tektona sandbox cp carries its own transfer program, so uploads and downloads work on an image with no shell and no /etc/passwd:

tektona sandbox cp ./app.tar 01JQXYZ123:/tmp/app.tar

So an image that runs one static binary is a valid sandbox: it starts, it serves its ports, and you can copy files in and out. Add a shell when you want to open a session in it.

Of the three, only the shell stops a session outright. An image with a shell and no /etc/passwd opens a working root session — you lose USER, LOGNAME and group membership, and you cannot name another user with --user. Ship an /etc/passwd when a session needs an identity, and when more than one user matters.

Limits

Next

On this page