Build a sandbox template
A template is a root filesystem plus defaults: environment, start command,
and ready check. This guide builds one from an OCI image, a Dockerfile, or a
snapshot, and then creates a sandbox from it. You need tritonctl signed in
to your cloud.
A template does not set a sandbox's size. The package you give at create time does.
The built-in templates are base (the default), code-interpreter, and
desktop. List them:
tritonctl sandbox template list --builtin true
Build from an OCI image
tritonctl sandbox template build py312 --image docker.io/library/python:3.12-slim --follow
The image's ENTRYPOINT, CMD, USER, WORKDIR, and ENV are kept. Only
amd64 images build.
A build is queued, and template build returns at once unless you add a wait
flag. --wait prints each status until the build is ready or failed.
--follow also prints the build log. Both exit non-zero when the build
fails.
For a private registry, give the user name and send the password or token on stdin:
printf '%s' "$REGISTRY_TOKEN" | tritonctl sandbox template build app \
--image registry.example.com/team/app:1.4 \
--registry-user ci --registry-password-stdin --wait
The credential is used for that build only, and the API never returns it.
Build from a Dockerfile
This source needs the templates_from_dockerfile feature gate, which your
operator turns on.
tritonctl sandbox template build api --dockerfile ./Dockerfile --context . \
--ready-port 8080 --follow
The context directory is sent as a tar of at most 1 MiB. Add --build-arg
for each build argument. The build runs in a separate builder sandbox.
--ready-port 8080 makes a new sandbox count as running only when port 8080
takes a TCP connection. Use --ready-cmd '<LINE>' instead to wait for a
shell line to exit 0.
Build from a snapshot
No build runs. The template is the snapshot's disk:
tritonctl sandbox template build devbox --from-snapshot dev/ready --wait
The source is <SANDBOX>/<SNAPSHOT>. This keeps a prepared sandbox after
the sandbox itself is deleted.
Create a sandbox from the template
tritonctl sandbox create --name t1 --template py312 --package sandbox-4g
--template takes name, name:tag, or name:<BUILD_ID>. Custom templates
are not in the booted pool, so the create boots cold.
Manage builds and tags
Each template build with a name in use adds a new build. The default tag
moves to the new build when it is ready, unless you give another --tag.
| Task | Command |
|---|---|
| Show a template and its builds | tritonctl sandbox template show py312 |
| Read a build log | tritonctl sandbox template logs py312 <BUILD_ID> |
| Point a tag at a build | tritonctl sandbox template tag py312 stable <BUILD_ID> |
| Remove a tag | tritonctl sandbox template untag py312 stable |
| Delete a template and all its builds | tritonctl sandbox template delete py312 |
If a build fails
| Symptom | Cause | Fix |
|---|---|---|
403 FeatureDisabled naming templates_from_dockerfile | Dockerfile builds are not on for your tenant. | Build from an OCI image, or ask your operator. |
"the build context <DIR> is larger than 1048576 bytes as a tar" | The context directory is larger than 1 MiB as a tar. tritonctl refuses it before it uploads anything. | Make the context smaller, or move the files into the image. |
| The build fails on an expired download link | The build waited more than an hour in the queue. | Run the build again. |
409 SandboxTemplateNotReady on create | The build is not ready yet. | Wait with --wait, then create. |