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
tektonaCLI 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-devThis 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 makespec.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-baseholds common developer tools.desktop-x11adds 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 defaultTektona 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 --sshThe 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 defaultThe 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 tagA build moves the tag that you name:
tektona template build run go-dev --tag stableA 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 01JABCDEF0123456789ABCDEFGA tag also keeps a version safe from the retention rules below.
References and scope
A template reference names a scope and a template:
| Reference | What it means |
|---|---|
go-dev | A template in your current project |
project/go-dev | The same thing, written out |
org/go-dev | A template your organization owns |
tektona/sandbox-base | A 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:
| Scope | Who reads it | Who builds and manages it |
|---|---|---|
project/… | project Reader | project Admin |
org/… | organization Member | organization Admin |
tektona/… | anyone | Tektona 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 it | A sandbox made from the version sees it |
|---|---|---|
| files (installed packages, config, anything on disk) | yes | yes: the disk is what the version captures |
export FOO=bar | no: each step is its own process | no |
cd /dir | no: each step starts in its workdir | no |
spec.build.env | yes, every step | no: 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-appThe 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 defaultImage 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 instruction | Effect |
|---|---|
ENV | Set in every SSH session, terminal and process. |
WORKDIR | The directory where a session starts, and where a build command that names no workdir runs. Tektona falls back to $HOME. |
ENTRYPOINT and CMD | By default, start at boot, even when the image has an init system. |
USER | The 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:
- the image
WORKDIR $HOME
$HOME is the first of these that applies:
- the passwd home of the user you name with
--user ENV HOMEin the image- the passwd home of the image
USER /, when the image declares no passwd entry for itsUSER
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/devFor 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=/workspaceENV 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:
- The
--envflag ontektona sandbox create. - An
ENV SHELLline in your image. - 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 ships | Without it |
|---|---|
An ENTRYPOINT or CMD | Nothing 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 names | tektona ssh fails with login: exec /bin/sh: no such file or directory. A shell is the program a session starts. |
An /etc/passwd file | A 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.tarSo 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
- The desktop needs an image that ships one. See
ghcr.io/tektona-ai/desktop-x11.
Next
Template Commands
The manifest, the build commands, and the flags that write each block.
Container Registries
Set up a credential, so that a build can pull a private image.
System Templates and Images
What ships in sandbox-base and desktop-x11, and how to extend them.
Template Version Lifecycle
How Tektona archives and deletes versions, and how to keep the ones you need.
Manage Sandboxes
Fork, pause, resume, set lifecycle timers, and delete sandboxes.
Git Repositories
Attach git repositories to a project so they're available to its sandboxes.