Merge pull request #24734 from dvdksn/fix/sbx-save-load-docs

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

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

@@ -174,3 +174,72 @@ 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 template 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
+```
+
+### List and remove templates
+
+List all saved templates:
+
+```console
+$ sbx template ls
+```
+
+Remove a template you no longer need:
+
+```console
+$ sbx template rm my-template:v1
+```
+
+### Export and import
+
+To share a saved template or move it to another machine, export it as a tar
+file:
+
+```console
+$ sbx template save my-sandbox my-template:v1 --output my-template.tar
+```
+
+On the other machine, load the tar file and use it:
+
+```console
+$ sbx template 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

@@ -26,7 +26,7 @@ see_also:
     - sbx reset - Reset all sandboxes and clean up state
     - sbx rm - Remove one or more sandboxes
     - sbx run - Run an agent in a sandbox
-    - sbx save - Save a snapshot of the sandbox as a template
     - sbx secret - Manage stored secrets
     - sbx stop - Stop one or more sandboxes without removing them
+    - sbx template - Manage sandbox templates
     - sbx version - Show Docker Sandboxes version information

data/sbx_cli/sbx_save.yaml

@@ -1,30 +0,0 @@
-name: sbx save
-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.
-usage: sbx save SANDBOX TAG [flags]
-options:
-    - name: help
-      shorthand: h
-      default_value: "false"
-      usage: help for save
-    - name: output
-      shorthand: o
-      usage: |
-        Save image to specified tar file instead of loading into host Docker
-inherited_options:
-    - name: debug
-      shorthand: D
-      default_value: "false"
-      usage: Enable debug logging
-example: |4-
-      # Load into host Docker (requires host Docker running)
-      sbx save my-sandbox myimage:v1.0
-
-      # Save to file (works without host Docker)
-      sbx save my-sandbox myimage:v1.0 --output /tmp/myimage.tar
-see_also:
-    - sbx - Manage AI coding agent sandboxes.

data/sbx_cli/sbx_template.yaml

@@ -0,0 +1,24 @@
+name: sbx template
+synopsis: Manage sandbox templates
+description: |-
+    Manage sandbox templates.
+
+    Templates are saved snapshots of sandboxes that can be reused to create new
+    sandboxes with: sbx run -t TAG AGENT [WORKSPACE]
+usage: sbx template COMMAND
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for template
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx - Manage AI coding agent sandboxes.
+    - sbx template load - Load an image from a tar file into the sandbox runtime
+    - sbx template ls - List template images
+    - sbx template rm - Remove a template image
+    - sbx template save - Save a snapshot of the sandbox as a template

data/sbx_cli/sbx_template_load.yaml

@@ -0,0 +1,27 @@
+name: sbx template 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 template save SANDBOX TAG --output FILE
+usage: sbx template 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 template load /tmp/myimage.tar              # Linux/macOS
+      sbx template load C:\Users\me\myimage.tar       # Windows
+
+      # Use the loaded image as a template
+      sbx run -t myimage:v1.0 claude
+see_also:
+    - sbx template - Manage sandbox templates

data/sbx_cli/sbx_template_ls.yaml

@@ -0,0 +1,26 @@
+name: sbx template ls
+synopsis: List template images
+description: |
+    List all template images stored in the sandbox runtime's image store.
+usage: sbx template ls [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for ls
+    - name: json
+      default_value: "false"
+      usage: Output in JSON format
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+example: |4-
+      # List all template images
+      sbx template ls
+
+      # Output in JSON format
+      sbx template ls --json
+see_also:
+    - sbx template - Manage sandbox templates

data/sbx_cli/sbx_template_rm.yaml

@@ -0,0 +1,20 @@
+name: sbx template rm
+synopsis: Remove a template image
+description: |
+    Remove a template image from the sandbox runtime's image store.
+usage: sbx template rm TAG [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for rm
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+example: |4-
+      # Remove a template image
+      sbx template rm myimage:v1.0
+see_also:
+    - sbx template - Manage sandbox templates

data/sbx_cli/sbx_template_save.yaml

@@ -0,0 +1,32 @@
+name: sbx template save
+synopsis: Save a snapshot of the sandbox as a template
+description: |-
+    Save a snapshot of the sandbox as a template.
+
+    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 template load FILE
+usage: sbx template save SANDBOX TAG [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for save
+    - name: output
+      shorthand: o
+      usage: Also export the image to a tar file
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+example: |4-
+      # Save as a template for new sandboxes on this host
+      sbx template save my-sandbox myimage:v1.0
+
+      # Also export to a shareable tar file
+      sbx template save my-sandbox myimage:v1.0 --output /tmp/myimage.tar
+see_also:
+    - sbx template - Manage sandbox templates