Skip to main content
A snapshot holds a machine’s installed software and its files under /data: home, workspace, and saved sign-ins (gh, Claude, Codex, git, SSH). It does not hold memory or running processes. Snapshots are private to you.
In the dashboard, choose Save snapshot in a machine’s menu. Then choose New machine from it, now or later on the Snapshots page.
Set up once, reuse everywhere. In the Playground, start a machine and install your tools, repos, and agent sign-ins in its terminal. Then choose Save as snapshot. Every machine you start from it is set up.

​
Save a running or stopped machine

  • A stopped machine saves as is.
  • A running machine is saved live. It keeps running, and the snapshot may leave out data programs have not written to disk yet.
  • A paused machine is refused with 409, and it cannot be stopped while paused. To save it, resume it, then save it live (or, where live saves are off, resume it, then stop it, then save). Files are kept either way.
snapshot save waits until the snapshot is saved, and --no-wait returns at once. --root-only saves only the installed software, so machines from it start with an empty home and workspace.

​
Fork a machine

fork (or clone) copies a running or stopped machine into one new machine, or up to 5 with --count. The copies have the same template and size, and fork waits until they run. The server copies the disks on the machine’s host and boots the copies in a few seconds, without a snapshot. Memory and running programs are not copied, and the source machine is not changed. What a fork keeps and when it uses a snapshot: Fork.
A paused machine cannot be forked, or stopped: resume it first. Each new machine counts toward your plan’s machine starts a minute, and fork waits that limit out. Each one also runs, so when your workspace cannot run --count more machines, fork creates none and says how many fit.
With an older server that has no native fork, a source host that is under maintenance or full, or with --keep-snapshot, fork saves a snapshot, creates the copies from it, then deletes the snapshot (also on error or Ctrl-C) unless --keep-snapshot. Over the API, a native fork is POST /v1/machines/{id}/fork.

​
Restore a machine in place

restore puts a machine’s disks back to a snapshot’s. The machine keeps its ID, name, hostname, public port URLs and ssh-config block, so everything that names it keeps working. Without --snapshot it restores the snapshot the machine was created from.
Everything on the root disk and /data since the snapshot is gone, running programs included. restore asks first, and --yes skips the question. To keep the machine as it is, use create --snapshot or fork instead.
A running machine is stopped first. Then it boots the restored disks, and the command waits until it runs. To leave it stopped, add --stopped. Its SSH host keys are new afterwards, so an SSH client that pinned them asks again. A snapshot saved --root-only, or whose /data is larger than the machine’s disk, is refused. Grow the disk first with instabox resize <machine> --disk N. Over the API, send POST /v1/machines/{id}/restore with {"snapshotId": "sn_..."} (machines:write). It answers with a restore operation.

​
Edge cases

A running machine on a server without live snapshots is refused like a paused one. Stop it, then save (api.instabox.sh has live snapshots on). If the save is refused because the machine has unsaved changes, stop it again, then retry.
instabox snapshot files dev-base /etc lists a snapshot’s files without starting a machine. Deleting a machine keeps its snapshots. Deleting a snapshot does not affect machines made from it. The free plan keeps snapshots. Older snapshots that hold installed software only start with an empty home and workspace, like --root-only ones.
POST /v1/machines/{id}/snapshots saves a snapshot, and GET /v1/snapshots lists them. POST /v1/machines with "snapshotId" starts a machine from one.

Custom images

Turn a Docker image into a snapshot.

Parallel forks

Run several agents from one set-up machine.