Snapshots & Copies

A snapshot is a point-in-time copy of a Box’s filesystem. You never take one by hand: Box captures them continuously in the background. Everything else on this page is a different way of using them.

Which one do I want?

Three things to do with a snapshot, and they get mixed up because they all come from the same one.

Resume gives you your Box back. Same Box, same id, new machine underneath.
Fork gives you a second Box holding a copy of the filesystem as it is right now. The original keeps running, untouched.
Template freezes a named copy that stays put. You deploy from it whenever you like, and it still works long after the Box it came from is gone.

Forking and deploying both give you a new Box with a copy of a filesystem, and you can do either as many times as you want. What differs is which copy: a fork takes the Box as it is at that moment and needs the Box to still exist, while a template is a point you named and froze, which you can return to weeks later and long after the original is gone. A rule of thumb: resume when you want your Box back, fork when you want a second one from where it stands right now, template when you want a fixed starting point to come back to.

What is captured

Captured

/home/user: your code, files, and configDocker named volumes (/var/lib/docker/volumes)Your changes under /etc, /usr, /opt, /root, /srv, cron tables, and the apt package database: installed packages, systemd services, system config

Not captured

The base OS and pre-installed tooling, which ship with the machine imageMachine identity: hostname, network config, SSH host keysRunning processes, memory, open ports

Coming back from a snapshot behaves like rebooting a server. Your files, installed packages and system setup return, and systemd services you enabled start again on their own. Processes you ran by hand do not survive; restart them, or make them a service. Snap packages are recorded and reinstalled. See Long-Running Tasks.

Excluding files with `.boxignore`

Build artifacts and dependency trees are worth nothing in a snapshot and slow every restore down. Nothing is left out of a snapshot unless you ask for it: write a .boxignore and every capture from the next one on obeys it.

cd ~/myapp
printf 'node_modules/\n.next/\n' > .boxignore

It uses gitignore syntax, and its rules are relative to the directory it sits in, so a .boxignore in a repo covers that repo and one in your home directory covers the whole Box. It is looked for up to six directories below your home directory, and the search skips node_modules, .next, target and vendor — put the file at the root of the tree you want skipped, not inside it. Your .gitignore is not used. It answers “do not commit this”, which is a different question from “it is safe to lose this on resume” — a build cache is routinely both. It is also not yours at all in a tool you installed as a git clone: ~/.nvm’s own .gitignore excludes v*, which is every node version you have installed. .git is always captured, since it is the one thing you cannot regenerate. Boxes created before this file was renamed still honour the old .oneignore name.

Automatic snapshots

Snapshots are incremental: the first is a full base, each later one stores only what changed, compressed, content-addressed and deduped against the base image. They are taken every minute while the Box is ready or idle, and a final one when it stops. If that final snapshot fails, the stop is aborted and the machine keeps running, so stopping can never lose data. Stopping at any moment is safe; the snapshot is always complete. Snapshots are kept for the life of the Box. Its latest can be resumed or forked whether it stopped yesterday or months ago. Superseded ones are cleaned up continuously as new ones are taken.

Resume

Brings the same Box back on a fresh machine, from its latest snapshot. Same Box id, same filesystem, new hardware.

box resume bx_f7k2q9hd
box resume bx_f7k2q9hd --type large      # different machine size
box resume bx_f7k2q9hd --ttl 7200        # new lifetime, in seconds
box resume bx_f7k2q9hd --no-auto-stop    # runs until you stop it

curl -sS -X POST "$BOX_API_BASE/boxes/bx_f7k2q9hd/resume" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"large","ttlSeconds":7200}'

await box.resume({
  boxId: "bx_f7k2q9hd",
  resumeRequest: { type: "large", ttlSeconds: 7200 },
});

box.resume(box_id="bx_f7k2q9hd", resume_request=ResumeRequest(type="large", ttl_seconds=7200))

Requires a completed snapshot, which means the Box was stopped cleanly with box stop. Shrinking to a smaller machine is refused if the Box holds more data than it can take, and the Box is left untouched. See Machines. Omit ttlSeconds to keep the Box’s current lifetime. Pass null (--no-auto-stop) to switch auto-stop off entirely.

Fork

Clones a Box from its latest snapshot into a new, independent Box. The source keeps running and is never modified.

box fork bx_f7k2q9hd
box fork bx_f7k2q9hd --type small
box fork bx_f7k2q9hd --ttl 600         # lifetime for the fork, in seconds
box fork bx_f7k2q9hd --no-auto-stop    # runs until you stop it

curl -sS -X POST "$BOX_API_BASE/boxes/bx_f7k2q9hd/fork" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"small","ttlSeconds":600}'

const forked = await box.fork({
  boxId: "bx_f7k2q9hd",
  forkRequest: { type: "small", ttlSeconds: 600 },
});

forked = box.fork(box_id="bx_f7k2q9hd", fork_request=ForkRequest(type="small", ttl_seconds=600))

The fork inherits the whole filesystem and the source’s per-Box variables unless you pass your own env. It also inherits the source’s exact environment version, so a fork never picks up configuration its source never had. See Environments. A fork does not inherit the source’s lifetime. It defaults to 1 hour, so a fork of a Box with auto-stop switched off is not itself left running forever. Pass ttlSeconds (or --no-auto-stop) when you want something else. Use fork for a throwaway copy right now: a second branch of work, a risky experiment, one machine per user of your product. If you find yourself forking the same Box repeatedly, make it a template instead.

Template Boxes

When many Boxes need the same stack pre-installed, build it once, save it under a name, and deploy from that name instead of installing on every fresh Box.

Create a Box and install everything: runtimes, packages, your app or daemon.
Save it: box snapshot <id> <name>. That freezes the Box’s disk at this moment under the name.
For each new Box: box new --from <name>. Deploys are usable in a few seconds, at roughly constant cost regardless of how much the template holds.

box new                            # install your stack, then:
box snapshot current web-stack     # freeze it under a name
box new --from web-stack           # deploy as many as you want
box snapshots                      # your named snapshots, then capture history
box snapshot rm web-stack          # remove it and release its storage

curl -sS -X POST "$BOX_API_BASE/named-snapshots" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"boxId":"bx_23456789","name":"web-stack"}'

curl -sS -X POST "$BOX_API_BASE/boxes" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"web-stack","environment":"users","env":{"TENANT_ID":"acme"}}'

await box.saveNamedSnapshot({
  namedSnapshotSaveRequest: { boxId: "bx_23456789", name: "web-stack" },
});

// poll until it settles at "ready"
const saved = await box.getNamedSnapshot({ name: "web-stack" });

await box.create({
  createBoxRequest: { from: "web-stack", environment: "users", env: { TENANT_ID: "acme" } },
});

await box.listNamedSnapshots();
await box.deleteNamedSnapshot({ name: "web-stack" });

from ascii_box_sdk.models.named_snapshot_save_request import NamedSnapshotSaveRequest

box.save_named_snapshot(NamedSnapshotSaveRequest(box_id="bx_23456789", name="web-stack"))

# poll until it settles at "ready"
saved = box.get_named_snapshot("web-stack")

box.create(CreateBoxRequest.from_dict({
    "from": "web-stack",
    "environment": "users",
    "env": {"TENANT_ID": "acme"},
}))

box.list_named_snapshots()
box.delete_named_snapshot("web-stack")

from is a reserved word in Python, so build that one request with from_dict as above rather than keyword arguments.

Saving from a running Box captures its current disk, taking a moment while a fresh snapshot lands. Saving from a stopped Box freezes its last snapshot. A named snapshot is a frozen copy, independent of the Box it came from. The source can keep changing, stop, or disappear, and the name still deploys the exact state you saved. Independent means independent: a Box’s snapshots form a chain that is periodically rebuilt from a fresh base with the old links cleaned up, and none of that touches your saved name. The save takes its own complete copy of everything needed to restore, so it never has to walk the source Box’s chain, and underlying data both still need is kept for as long as either one refers to it. A saved name has no expiry. You can keep up to 10, and each shows its size in box snapshots.

Templates are not environments

A template holds the disk. An environment holds the configuration. They are different tools and most setups use both.

	Template Box	Environment
Holds	Installed packages, builds, caches, warm state	Repositories to clone, secrets, credentials
Answers	”What is already on this machine?"	"What is this machine allowed to have?”
Costs	Storage, and a few seconds per deploy	Nothing
Changing it	Re-save the name. Deployed Boxes are unaffected	Mints a version. Running Boxes move only on upgrade
Applies at	Deploy time, once	Every start, resume, and fork

If you would put it in a Dockerfile it belongs in a template; if you would put it in a .env it belongs in an environment. Compose them:

box new --from web-stack --environment users --env TENANT_ID=acme

That Box boots with your stack already installed, none of your credentials inside it, and one variable of its own.

Deploying from a template does not carry the source Box’s named environment. The new Box is pinned by --environment, or by your default environment when you omit it. A template built while you were logged into your own GitHub does not leak that access to its deploys.Its per-Box variables do carry, the same way they do on a fork: anything you passed as --env KEY=VALUE to the source Box is set on every deploy from that name, unless the deploy passes its own env. Do not put a secret in --env on a Box you are about to save as a template.

Updating a template

Save the same name again: resume the Box (or any Box set up the way you want), update the stack, and run box snapshot <id> <name> with the existing name. The name points at the new state and the old artifact is released. Boxes already deployed from it are unaffected. If a re-save fails, the name keeps deploying the last good save.

What happens on restore

A resume, fork or deploy is usable in a few seconds, whatever the Box holds. The full file tree is there immediately, every file is readable on demand, and content finishes downloading in the background. Permissions, ownership, timestamps and extended attributes come back with your files, and on directories too. Two details are worth knowing:

Extended attributes on a file become readable once that file’s content has arrived. Directories carry theirs from the moment the Box is up.
Directory modification times are restored once the background download finishes rather than immediately, because writing a file into a directory updates that directory’s timestamp, so setting it any earlier would just be overwritten.

Warming for faster first boots

A Box records the order in which files are first opened while it is starting up, and keeps that order in .ascii/playbook.json. On the next start those files are fetched first, so your app reaches a working state before the rest of the disk has arrived. The playbook is an ordinary file, so it is captured into the snapshot and every fork or deploy inherits it. Recording only happens while a Box is starting up from a snapshot, so the order matters:

Start the Box from a snapshot

Resume a stopped Box, or deploy one from the template you are about to update. A Box created from scratch has nothing to record against.

box resume bx_f7k2q9hd

Boot your app straight away

Run the normal startup, right away, while the Box is still filling in. Every file it opens is recorded in the order it asks for them. Files opened later, once the Box has finished filling in, are not recorded.

box exec bx_f7k2q9hd "cd my-repo && npm run dev"

Let it finish, then save

The playbook is written when the Box finishes filling in. Save after that, or the run you just did is not in the template.

box snapshot bx_f7k2q9hd web-stack

Each run merges into the previous playbook rather than replacing it, with the newest run weighted highest, so a template warms up further every time you repeat this. It holds the first 5000 paths.

Retention

By default, snapshots are kept for the life of the archived Box: its latest snapshot can be resumed or forked whether it stopped yesterday or months ago. Superseded snapshots are cleaned up continuously as new ones are taken. Permanent deletion is different from archive. Deleting a Box or snapshot returns a background operation and makes the target unavailable; it cannot be resumed. Named snapshots remain independent of their source Box. When you remove one, its backing data is scheduled no earlier than six hours later so already-issued signed upload URLs expire first. With zero data retention, archived Box data and named snapshots are queued for deletion instead of retained.

Inspect and download

box snapshots                                 # across your boxes
box snapshot latest bx_f7k2q9hd
box snapshot tree <snapshotId>                # files + sizes
box snapshot pull <snapshotId> -o ./restore   # download and reassemble

curl -sS "$BOX_API_BASE/snapshots" \
  -H "Authorization: Bearer $BOX_API_KEY"
curl -sS "$BOX_API_BASE/boxes/bx_f7k2q9hd/snapshots/latest" \
  -H "Authorization: Bearer $BOX_API_KEY"
curl -sS "$BOX_API_BASE/snapshots/<snapshotId>/tree" \
  -H "Authorization: Bearer $BOX_API_KEY"

# grab one file (or a folder as .tar) straight from a snapshot; box can be stopped
curl -sS "$BOX_API_BASE/snapshots/<snapshotId>/files?path=projects/app/.env" \
  -H "Authorization: Bearer $BOX_API_KEY" -o .env
curl -sS "$BOX_API_BASE/snapshots/<snapshotId>/files?path=projects/app" \
  -H "Authorization: Bearer $BOX_API_KEY" -o app.tar

await box.listSnapshots();                                   // across your boxes
await box.listBoxSnapshots({ boxId: "bx_f7k2q9hd" });        // one box's history
await box.getLatestBoxSnapshot({ boxId: "bx_f7k2q9hd" });
await box.getSnapshotTree({ snapshotId: "<snapshotId>" });   // files + sizes

const file = await box.getSnapshotFile({
  snapshotId: "<snapshotId>",
  path: "projects/app/.env",
});
const archive = await box.getSnapshotDownload({ snapshotId: "<snapshotId>" });

box.list_snapshots()                          # across your boxes
box.list_box_snapshots("bx_f7k2q9hd")         # one box's history
box.get_latest_box_snapshot("bx_f7k2q9hd")
box.get_snapshot_tree("<snapshotId>")         # files + sizes

file = box.get_snapshot_file("<snapshotId>", path="projects/app/.env")
archive = box.get_snapshot_download("<snapshotId>")

pull writes two subfolders, home_user/ (your /home/user) and docker/ (named volumes), reflecting exactly the files that were live at that snapshot. There is no SDK equivalent of pull: it is getSnapshotDownload plus local reassembly. Browse the same tree, and download files from it, on the Snapshots tab of the dashboard. See the Snapshots API for the full surface.

Deleting a Box’s snapshots

Stopping a Box keeps its snapshots, that is the whole point of stopping. Deleting a Box throws them away.

Deleting a Box force-stops it and permanently deletes its snapshots. It cannot be resumed, forked or recovered afterwards, and there is no deleted-Boxes list to restore from.If you want the data usable later, stop the Box instead of deleting it. A stopped Box is free, keeps its disk, and resumes where you left off.

box stop bx_f7k2q9hd            # keeps the data; `box resume` brings it back
box delete bx_f7k2q9hd          # deletes the Box AND its snapshots, permanently
box delete bx_f7k2q9hd --yes    # same, without the confirmation prompt

curl -sS -X DELETE "$BOX_API_BASE/boxes/bx_f7k2q9hd" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "X-Ascii-Confirm-Delete: bx_f7k2q9hd"

await box.deleteBox({
  boxId: "bx_f7k2q9hd",
  xAsciiConfirmDelete: "bx_f7k2q9hd",
});

box.delete_box(
    x_ascii_confirm_delete="bx_f7k2q9hd",
    box_id="bx_f7k2q9hd",
)

Every delete has to name its own target: X-Ascii-Confirm-Delete must equal the Box id exactly, or the request is refused with 409 and nothing is deleted. See Data retention and deletion for the operation you get back and how to poll it. You can also delete a Box from the ⋯ menu on its row in the dashboard. The Box leaves your account immediately; the snapshot data goes once the machine has finished shutting down. What survives, and why. Snapshots are shared: a fork, a resume and a deploy from a template all read the same physical objects as the Box they came from. Deleting a Box therefore only removes the snapshot data nothing else is using. Kept are:

chains a Box forked or resumed from this one still restores from
named snapshots saved from this Box, which are meant to outlive it. Delete those with box snapshot rm <name> when you want the bytes gone.

Storage is released once the last Box or named snapshot using a chain is gone.

Why filesystem, not the VM

Snapshots capture the filesystem, independent of the machine running underneath. Today a Box is a Hetzner VPS, but a Box is meant to become anything: a Linux server, a Mac or Windows machine in the cloud, or a physical device. A filesystem snapshot stays portable across all of them, restores fast, stays small, and lets us filter what is captured as needs grow. A whole-VM image would tie you to one kind of machine.

​Which one do I want?

​What is captured

Captured

Not captured

​Excluding files with .boxignore

​Automatic snapshots

​Resume

​Fork

​Template Boxes

​Templates are not environments

​Updating a template

​What happens on restore

​Warming for faster first boots

​Retention

​Inspect and download

​Deleting a Box’s snapshots

​Why filesystem, not the VM

​Related

Which one do I want?

What is captured

Excluding files with `.boxignore`

Automatic snapshots

Resume

Fork

Template Boxes

Templates are not environments

Updating a template

What happens on restore

Warming for faster first boots

Retention

Inspect and download

Deleting a Box’s snapshots

Why filesystem, not the VM

Related