Skip to main content
A snapshot saves the parts of the disk that you changed. It does not save the operating system that every machine already has.

​
Saved and not saved

Saved

/home/user: your code, files and settingsDocker named volumes (/var/lib/docker/volumes)Your changes in /etc, /usr, /opt, /root and /srv, cron tables, and the apt package list. This means installed packages, systemd services and system settings.

Not saved

The operating system and the tools that come with every machineThe identity of the machine: hostname, network settings, SSH host keysYour cache folder ~/.cache (read more)Running programs, memory and open portsThe Docker build cache, and images that no container uses (read more)

​
Deleted files stay deleted

A deletion is a change, so the snapshot saves it too. For example, remove a coding agent that comes with the machine:
The agent stays gone after every resume, fork and template deploy. The same is true for an apt package that you remove. If you install your own copy of a tool, your copy is used, not the one that comes with the machine.

​
A restore is like a reboot

When a sandbox comes back from a snapshot, it is like a server that restarts.
  • Your files, packages and system settings are there.
  • Systemd services that you enabled start again by themselves.
  • Programs that you started by hand are not running. Start them again, or make them a service.
  • Snap packages are reinstalled.
To keep a program running across stops, read Long-Running Tasks.

​
Docker builds

Docker and BuildKit are installed. While a sandbox runs, docker build uses its layer cache as usual. A rebuild with no change takes less than one second. The layer cache is in /var/lib/docker, and a snapshot does not save it. After a resume, or on a fork, the first build starts from zero. It downloads its base images again. Your running containers come back with the image they used. Only the build cache is lost. To keep the build cache, save it in your home folder:
We measured this on a Node app with a slow dependency install: Named volumes keep their data in all cases.

​
Tool caches

A snapshot does not save ~/.cache. Tools that download files into it download them again after a resume or a fork. Playwright is the most common case. By default, it installs its browsers in ~/.cache/ms-playwright. To keep these files, install them in a different folder. For Playwright, set PLAYWRIGHT_BROWSERS_PATH. Put it on the first line of ~/.bashrc. Then boat ssh, boat ssh <id> "<command>" and boat exec all use it.
A service that runs Playwright needs the same variable. In a systemd unit, add Environment=PLAYWRIGHT_BROWSERS_PATH=....

​
Leave files out with .boxignore

Build output and dependency folders slow down every restore, and you can make them again. To leave them out of snapshots, write a .boxignore file. The next snapshot uses it.
  • It uses the same rules as .gitignore.
  • Its rules apply to the folder that it is in. A .boxignore in a repo applies to that repo. A .boxignore in your home folder applies to the whole sandbox.
  • Boat looks for it up to six folders below your home folder. It does not look inside node_modules, .next, target or vendor.
  • Put the file at the top of the folder that you want to leave out, not inside it.
  • .git is always saved, because you cannot make it again.
  • Older sandboxes also read the old name, .oneignore.
Boat does not read your .gitignore. A .gitignore lists files that you do not commit. That is not the same as files that you can lose. Also, a tool that you install with git clone has its own .gitignore. For example, the .gitignore of ~/.nvm lists every Node version that you install.