Skip to content
pols.so docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Snapshots and forks

Copy a sandbox's disk into a new running sandbox to branch work, try risky changes or run things in parallel.

pols copies disks instead of rebuilding them. Every copy is a ZFS snapshot and clone on the host, so it takes well under a second no matter how much is on the disk. You use copies in two ways:

  • Fork a sandbox to get a second, independent sandbox that starts from its disk, right now.
  • Save a template to keep a disk as a starting point for many future sandboxes; see Templates.

Forking

pols fork web --name web-try
pols fork web --name web-locked --egress none
pols fork web --name web-ci --secret CI_TOKEN

pols fork (POST /v1/sandboxes/{sandbox}/fork) snapshots the source sandbox’s disk, clones it into a new VM and starts that VM. The source may be running or stopped, and it stays as it was. The fork:

  • is a new sandbox with its own ID and name, the same size as the source, on the same host;
  • gets a new machine ID and new SSH host keys on its first boot;
  • keeps the source’s egress policy unless you set one;
  • keeps the source’s environment variables and vault entries, and adds the ones you name with --secret;
  • records its origin in source_sandbox_id.

Forking checks the same quotas as creating a sandbox. For a different size, save a template and create a sandbox from it.

What a fork contains

A fork starts from the source’s disk, not its memory: it boots fresh, so processes that ran in the source are not running in the fork, and data an application held only in memory is not there. Databases and other services that write to disk recover from it as they would after a power cut. For a clean copy of a running database, stop it (or the whole sandbox) before forking.

Snapshots when stopping

Each time a sandbox stops, the host also takes a snapshot of its disk and keeps the last three. These snapshots belong to the sandbox and are deleted with it. They are not exposed through the API yet: you cannot list them or roll back to one. To keep a state you can return to, fork the sandbox or save a template.

Typical uses

  • Try something risky. Fork, run the migration or upgrade in the fork, and delete whichever sandbox you no longer need.
  • Fan out work. Prepare one sandbox, fork it once per task, and let an agent work in each fork in parallel.
  • Reproduce a bug. Fork the sandbox where it happens and investigate the copy while the original keeps running.