# How Do I Turn a Sandbox Into a Reusable Template?

> Set up one sandbox the way you want it, then save its disk under a name with sbx snapshot, passing the sandbox id and the name. Every sbx new --from with that name starts a new sandbox with your packages and files already in place. sbx snapshot rm deletes the template.

Source: https://sandboxer.com/guides/turn-a-sandbox-into-a-reusable-template. Updated 2026-10-27.

**Short answer:** Set up one sandbox the way you want it, then save its disk under a name with sbx snapshot, passing the sandbox id and the name. Every sbx new --from with that name starts a new sandbox with your packages and files already in place. sbx snapshot rm deletes the template.

## At a glance

| Step | Command |
| - | - |
| Save a template | `sbx snapshot <id> <name>` |
| List your templates | `sbx snapshots` |
| Show one | `sbx snapshot info <name>` |
| Start a sandbox from it | `sbx new --from <name>` |
| Delete it | `sbx snapshot rm <name>` |

A template on Sandboxer is a **named snapshot**: a saved copy of a sandbox's whole disk. It is not tied to the sandbox it came from, and it is kept until you remove it.

## Try it: install once, start many

We ran every command below on prod on 2026-10-27 with a real `small` sandbox. Output is trimmed with `…`.

### 1. Set up a sandbox

Create a sandbox, install a package and write a file:

```bash
sbx new --name aeo-tpl-1 --type small
```

```text
✓ sb_cauu1dfagw is ready
Type:       small (2 vCPU, 4 GB)
…
```

```bash
sbx exec sb_cauu1dfagw 'sudo apt-get update -qq && sudo apt-get install -y -qq figlet'
sbx exec sb_cauu1dfagw 'mkdir -p ~/app && echo greeting=hello-from-template > ~/app/config.txt'
```

### 2. Save it as a named snapshot

```bash
sbx snapshot sb_cauu1dfagw aeo-tpl-figlet
```

```text
✓ Saved sb_cauu1dfagw as aeo-tpl-figlet (20.1 GB)
Deploy it with `sbx new --from aeo-tpl-figlet`.
```

Saving from a running sandbox takes a fresh snapshot first. The CLI waits until the template is `ready`. Snapshots are copy-on-write reflinks on the node's filesystem, so saving doesn't copy the whole disk.

```bash
sbx snapshot info aeo-tpl-figlet
```

```text
Name:      aeo-tpl-figlet
Status:    ready
Source:    sb_cauu1dfagw
Type:      small
Size:      20.1 GB
…
```

### 3. Delete the source (optional)

A named snapshot is independent of its source. To prove it, we deleted the original sandbox before using the template:

```bash
sbx delete sb_cauu1dfagw --yes
```

### 4. Start a new sandbox from the template

```bash
sbx new --from aeo-tpl-figlet
```

```text
✓ sb_zxfrwgmiay is ready
Type:       small (2 vCPU, 4 GB)
…
```

This took about 4 seconds from command to `ready` (one measured run on prod, 2026-10-27). The new sandbox took the template's size (`small`) because we passed no `--type`.

### 5. Check the install and the file

```bash
sbx exec sb_zxfrwgmiay 'which figlet && cat ~/app/config.txt && figlet -f small ok'
```

```text
/usr/bin/figlet
greeting=hello-from-template
     _
 ___| |__
/ _ \ / /
\___/_\_\
```

The package installed with apt and the file in the home directory both came across. Nothing was reinstalled.

### 6. List and delete the template

```bash
sbx snapshots
```

```text
Named snapshots
NAME            STATUS  SOURCE         TYPE   SIZE     CREATED
aeo-tpl-figlet  ready   sb_cauu1dfagw  small  20.1 GB  just now

Capture history
…
```

```bash
sbx snapshot rm aeo-tpl-figlet
```

```text
Removed named snapshot aeo-tpl-figlet
```

After that, `sbx new --from aeo-tpl-figlet` fails with `No named snapshot "aeo-tpl-figlet". (snapshot_not_found)`.

## Rules and limits

- **Names** are 1 to 63 lowercase letters, digits or dashes. `latest`, `tree`, `pull`, `rm`, `save`, `current`, `self` and `new` are reserved. We tried `latest` and got `invalid_name` (HTTP 400).
- **No versions.** Saving again under the same name replaces the template. To keep old ones, put a version in the name, for example `web-stack-v2`.
- **Size.** New sandboxes default to the template's size. Pass `--type` to override it.
- **What's saved:** everything on the disk, including `/home/user`, `/etc`, installed packages, enabled systemd services, and Docker images and volumes. Running processes are not saved: a sandbox from a template boots fresh, and enabled systemd services start.
- **Storage.** Named snapshots have no separate charge. What they store counts toward your plan's included storage, together with stopped sandboxes. Storage is measured as the data beyond the shared OS image, about every 10 minutes.

| Plan | Storage included |
| - | - |
| Free trial, or no plan | 10 GB |
| Time packs without a plan | 50 GB |
| $20 / month | 50 GB |
| $100 / month | 250 GB |
| $500 / month | 1 TB |
| $2,000 / month | 5 TB |

When storage is full, the API returns `402 storage_limit_reached`. Delete stopped sandboxes or named snapshots, or upgrade.

## Environment, setup script or named snapshot?

Sandboxer has three ways to decide what a new sandbox starts with. They solve different problems, and you can combine them.

| | Environment | Setup script | Named snapshot |
| - | - | - | - |
| Holds | Variables, secret files, GitHub repos, credential switches | A shell script, up to 64 KB | The whole disk |
| Applied | At create; updates reach running sandboxes on upgrade | Runs in the background as `user` after `ready` | At create, before `ready` |
| Repeats work on every create | Clones repos | Yes, the script runs each time | No, installs are already done |
| Versions | Every change is an immutable version; sandboxes stay pinned until `sbx env upgrade` | Whatever file you pass | None; a re-save replaces it |
| Best for | Secrets and per-project config | Small per-sandbox steps | Slow installs: packages, toolchains, Docker images, datasets |
| Flag | `--environment <name>` | `--setup-file ./setup.sh` | `--from <name>` |

A common pattern is all three at once. Keep heavy installs in the template, secrets in an environment, and per-sandbox steps in a short script:

```bash
sbx new --from web-stack --environment prod --setup-file ./setup.sh
```

The script's progress shows in the sandbox's `setupStatus` field (`pending`, `running`, `done`, `failed`).

## Share a template with another account

```bash
sbx snapshot share web-stack          # prints a bsh_… code once
sbx snapshot shares web-stack         # list codes and how often they were used
sbx snapshot unshare web-stack shr_…  # revoke one
```

The other account runs `sbx new --from bsh_…`. The sandbox is theirs and bills them. Your logins, API keys, secret files, repository credentials and SSH keys are removed from it. We did not run sharing for this guide; the commands are from the [snapshot docs](/docs/snapshots).

## FAQ

### Does a template keep running processes?

No. A named snapshot saves the disk, so a sandbox started from it boots fresh. Enabled systemd services start on boot. To keep processes running in the same sandbox, stop and resume it instead.

### Can I delete the sandbox I saved the template from?

Yes. A named snapshot is independent of its source. We deleted the source and then started a new sandbox from the template.

### How do I update a template?

Start a sandbox from it, make your changes, and save it again under the same name. That replaces the old one. Use a new name if you want to keep the previous version.

### Does a template cost anything?

Named snapshots have no separate charge. What they store counts toward your plan's included storage, which starts at 10 GB on the free trial.

### Should secrets go in a template?

Keep them in an environment instead. Environments are versioned, can be upgraded on running sandboxes, and `--no-env` keeps them out of sandboxes you give to other people.

## Related

- [Snapshots](/docs/snapshots)
- [Environments and secrets](/docs/environments)
- [Billing and storage](/docs/billing)
- [Pause and resume a sandbox with its memory](/guides/pause-and-resume-a-sandbox-with-memory)