From 2204af5551edc83e9ea39556062c0fe9f19f56f0 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 15 Apr 2026 10:20:50 +0200 Subject: [PATCH] docs: add sbx save/load snapshot workflow to custom environments The custom environments page only documented Dockerfile-based templates pushed to a registry. Added a section covering the sbx save/load workflow for saving a sandbox's state as a reusable local template, including export/import via tar files and known limitations. Co-Authored-By: Claude Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- .../sandboxes/agents/custom-environments.md | 55 +++++++++++++++++++ data/sbx_cli/sbx.yaml | 1 + data/sbx_cli/sbx_load.yaml | 26 +++++++++ data/sbx_cli/sbx_save.yaml | 14 +++-- 4 files changed, 90 insertions(+), 6 deletions(-) create mode 100644 data/sbx_cli/sbx_load.yaml diff --git a/content/manuals/ai/sandboxes/agents/custom-environments.md b/content/manuals/ai/sandboxes/agents/custom-environments.md index 260f985f553..1d78c61cc5d 100644 --- a/content/manuals/ai/sandboxes/agents/custom-environments.md +++ b/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 +``` diff --git a/data/sbx_cli/sbx.yaml b/data/sbx_cli/sbx.yaml index 0cdde692106..52f914b1b37 100644 --- a/data/sbx_cli/sbx.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_load.yaml b/data/sbx_cli/sbx_load.yaml new file mode 100644 index 00000000000..df902ef4f9f --- /dev/null +++ b/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. diff --git a/data/sbx_cli/sbx_save.yaml b/data/sbx_cli/sbx_save.yaml index 3239e15ef8e..b74ff5ad0ac 100644 --- a/data/sbx_cli/sbx_save.yaml +++ b/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.