sbx template save and sbx template load

You spent an hour inside m101-demo installing a toolchain, and tomorrow a second sandbox needs the same tools without the hour. The capture leaves a marker file at /opt/marker-from-demo, saves the sandbox as m101-tpl:v1, and creates m101-from-tpl from it. When you finish this section, you can save a template, start a sandbox from it, and carry it to another host as a tar.

What a template holds

Template: a saved snapshot of a sandbox's container filesystem, stored as an image. You create new sandboxes from it with sbx run --pull never -t TAG AGENT [WORKSPACE]. The docs draw the line between image and kit. A template holds image content, and the agent kit still supplies the runtime settings, such as credentials and network rules. Mounted filesystems are not in it, because a saved template is not a backup of the whole sandbox.

That excludes host workspaces and the Docker store at /var/lib/docker. Everything else in the container filesystem is in it, including any key an agent wrote to a file. Keep credentials in sbx secret and the proxy instead. Agent configuration files such as /home/agent/.claude/settings.json are written again every time a sandbox is created, so a change there does not survive either.

Every built-in agent starts from docker/sandbox-templates:<variant>, and m101-demo pulled docker/sandbox-templates:shell-docker. A variant with a -docker suffix includes Docker Engine, so you can build and run containers inside the sandbox. That is why docker version answers inside m101-demo. With platform.images.useDHI set, the default template docker/sandbox-templates:claude-code-docker changes to dhi/sbx-templates:claude-code-docker, and the tag stays the same.

sbx template save

sbx template save SANDBOX TAG needs a stopped sandbox. The capture tries it on the running m101-demo, reads cannot save a running sandbox, stops it, and saves m101-tpl:v1. The image goes to the image store of the sandbox runtime. That store is separate from the image store of the Docker daemon on the host. The 2025 plugin's docker sandbox save loaded the image into the host daemon by default, and --output was the way to a file, as conflict C32 records.

$ sbx template save m101-demo m101-tpl:v1 --output $CAPTURE/work/m101-tpl.tar
Sandbox m101-demo is running and must be stopped before saving. Stop it now? (y/N): error: cannot save a running sandbox; stop it first with:
  try: sbx stop m101-demo
[exit 1]

$ sbx stop m101-demo
Sandbox 'm101-demo' stopped; state preserved. Restart with: sbx run --name m101-demo
[exit 0]

$ sbx template save m101-demo m101-tpl:v1 --output $CAPTURE/work/m101-tpl.tar
Snapshotting image in sandbox ...
Exporting image to $CAPTURE/work/m101-tpl.tar ...
Exported to $CAPTURE/work/m101-tpl.tar

Save complete. To use the image as a template:
    sbx run --pull never -t docker.io/library/m101-tpl:v1 AGENT [WORKSPACE]
[exit 0]

sbx template ls --json then lists three images: the base docker.io/docker/sandbox-templates:shell-docker, the new docker.io/library/m101-tpl:v1 with flavor shell, and docker.io/sandboxes-swap/m101-demo:bf19e491. The last one is an image the runtime keeps for the stopped sandbox, and it is gone once every sandbox is removed. Each record has id, repository, tag, flavor, created_at, and size, and the capture masks the id, so this manual does not state its format.

{
  "images": [
    …
    {
      "id": "<id>",
      "repository": "docker.io/library/m101-tpl",
      "tag": "v1",
      "flavor": "shell",
      "created_at": "<ts>",
      "size": "<n>"
    },
    …
  ]
}

Reuse with --pull never -t

Reuse is sbx run --pull never -t TAG AGENT [WORKSPACE], and the help explains the flag: --pull never uses the saved image and does not try a registry. The capture uses sbx create --pull never -t m101-tpl:v1 shell --name m101-from-tpl, reads Checking image instead of Pulling image, and finds /opt/marker-from-demo inside the new sandbox. Name the agent that the template was built for. A Claude template run with codex prints a warning that the sandbox can fail to work correctly.

$ sbx create --pull never -t m101-tpl:v1 shell --name m101-from-tpl

sandbox    m101-from-tpl
agent      shell
workspace  none · no workspace bind mount
image      m101-tpl:v1
cpu        10
memory     32 GiB

Checking image
✓ Image ready
✓ Created sandbox m101-from-tpl
…
$ sbx exec m101-from-tpl sh -c 'ls -l /opt/marker-from-demo'
-rw-r--r-- 1 root root 0 <date> /opt/marker-from-demo
[exit 0]

sbx template inspect works only in the cloud in v1, and it needs --cloud. The local attempt in the capture exits 1 with a hint to run docker image inspect -- m101-tpl:v1. That command reads the host daemon's store, which the runtime does not share, so use sbx template ls for a local template. sbx template rm m101-tpl:v1 --force prints Removed: m101-tpl:v1, and sbx reset clears the cached images too.

Export and load

--output FILE on save also writes a tar. work/m101-tpl.tar has 24 entries and starts with blobs/sha256/, the layout of an OCI image. On the other host, sbx template load FILE loads the image from the tar file into the image store of the sandbox runtime, and sbx run --pull never -t m101-tpl:v1 shell starts from it. The capture did not load the tar on a second machine, so figure 2.2 draws that step from the help text. The same path imports an image that you built yourself: docker image save writes the tar, and sbx template load imports it. So no registry needs to serve the image when the sandbox is created.

In the cloud, sbx --cloud template load FILE NAME needs --cpus and --memory-mib that together name a billable shape. The shapes run from micro, 1 vCPU and 2048 MiB, to xl, 16 vCPU and 32768 MiB. --capture-mode all adds memory and a microVM checkpoint to the disk capture. Tier C was not recorded, so this manual shows no cloud listing, and sbx --cloud cites the help text instead.