docs: add sbx save/load snapshot workflow to custom environments

content/manuals/ai/sandboxes/agents/custom-environments.md

@@ -174,3 +174,58 @@ Because this template extends the `claude-code` base image, you run it with
 Template images are cached locally. The first use pulls from the registry;
 subsequent sandboxes reuse the cache. Cached images persist across sandbox
 creation and deletion, and are cleared when you run `sbx reset`.
+
+## Saving a sandbox as a template
+
+Instead of writing a Dockerfile, you can save a running sandbox's state as a
+template. This captures installed packages, configuration changes, and files
+into a reusable image — useful when you've set up an environment interactively
+and want to preserve it.
+
+### Save and reuse
+
+Stop the sandbox (or let the CLI prompt you), then save it with a name and
+tag:
+
+```console
+$ sbx save my-sandbox my-template:v1
+```
+
+The image is stored in the sandbox runtime's local image store. Create a new
+sandbox from it with the `-t` flag:
+
+```console
+$ sbx run -t my-template:v1 claude
+```
+
+### Export and import
+
+To share a saved template or move it to another machine, export it as a tar
+file:
+
+```console
+$ sbx save my-sandbox my-template:v1 --output my-template.tar
+```
+
+On the other machine, load the tar file and use it:
+
+```console
+$ sbx load my-template.tar
+$ sbx run -t my-template:v1 claude
+```
+
+### Limitations
+
+Agent configuration files are always recreated when a sandbox is created.
+Changes to user-level agent configuration files, such as
+`/home/agent/.claude/settings.json` and `/home/agent/.claude.json`, do not
+persist in saved templates.
+
+If the saved template was built for a different agent than the one you
+specify in `sbx run`, you get a warning. For example, saving a Claude
+sandbox and running it with `codex` produces:
+
+```text
+⚠ WARNING: template "my-template:v1" was built for the "claude" agent but you are using "codex".
+  The sandbox may not work correctly. Consider using: sbx run -t my-template:v1 claude
+```

data/sbx_cli/sbx.yaml

@@ -18,6 +18,7 @@ see_also:
     - sbx completion - Generate the autocompletion script for the specified shell
     - sbx create - Create a sandbox for an agent
     - sbx exec - Execute a command inside a sandbox
+    - sbx load - Load an image from a tar file into the sandbox runtime
     - sbx login - Sign in to Docker
     - sbx logout - Sign out of Docker
     - sbx ls - List sandboxes

data/sbx_cli/sbx_load.yaml

@@ -0,0 +1,26 @@
+name: sbx load
+synopsis: Load an image from a tar file into the sandbox runtime
+description: |-
+    Load an image from a tar file into the sandbox runtime's image store.
+
+    The loaded image can be used as a template for new sandboxes.
+    Tar files are typically created with: sbx save SANDBOX TAG --output FILE
+usage: sbx load FILE [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for load
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+example: |4-
+      # Load an image from a tar file
+      sbx load /tmp/myimage.tar
+
+      # Use the loaded image as a template
+      sbx run -t myimage:v1.0 claude
+see_also:
+    - sbx - Manage AI coding agent sandboxes.

data/sbx_cli/sbx_save.yaml

@@ -3,8 +3,11 @@ synopsis: Save a snapshot of the sandbox as a template
 description: |-
     Save a snapshot of the sandbox as a template.
 
-    By default, the image is loaded into the host's Docker daemon (requires Docker to be running).
-    Use --output to save the image to a tar file instead.
+    The saved image is stored in the sandbox runtime's image store and can be
+    used as a template for new sandboxes with: sbx run -t TAG AGENT [WORKSPACE]
+
+    Use --output to also export the image to a tar file that can be shared
+    and loaded on another host with: sbx load FILE
 usage: sbx save SANDBOX TAG [flags]
 options:
     - name: help
@@ -13,18 +16,17 @@ options:
       usage: help for save
     - name: output
       shorthand: o
-      usage: |
-        Save image to specified tar file instead of loading into host Docker
+      usage: Also export the image to a tar file
 inherited_options:
     - name: debug
       shorthand: D
       default_value: "false"
       usage: Enable debug logging
 example: |4-
-      # Load into host Docker (requires host Docker running)
+      # Save as a template for new sandboxes on this host
       sbx save my-sandbox myimage:v1.0
 
-      # Save to file (works without host Docker)
+      # Also export to a shareable tar file
       sbx save my-sandbox myimage:v1.0 --output /tmp/myimage.tar
 see_also:
     - sbx - Manage AI coding agent sandboxes.