Get Started
FORK & SCALE

Fork Without Stopping Work

Take a copy of a box in the middle of a build or an agent session, and leave the original running.

You are forty minutes into a build, or an agent is in the middle of a task, and you want a second box at exactly this state: to try a risky change, to hand the work to another agent, or to keep a checkpoint. Stopping the box would kill what is running.

You do not have to stop it. run9 pauses the box for a moment, captures its file system, and lets the same processes continue.

An older CLI asks you to stop the box first. If you see that message, update the CLI.

What you are building

box: builder  (job keeps running)
       |
       |  fork, brief pause
       v
snap: <forked-snap-id>
       |
       v
box: builder-copy  (same files, fresh processes)

Start a job that keeps writing

sys9 run box create builder
sys9 run box exec builder mkdir -p /work
sys9 run box exec-bg builder /bin/sh -lc 'i=1; while [ "$i" -le 30 ]; do echo "step $i" >> /work/progress.log; i=$((i+1)); sleep 10; done'

Keep the exec_id from the last command. The job appends one line every ten seconds for five minutes.

Fork while it runs

sys9 run snap fork --from-box builder

The box pauses briefly and then resumes. The command keeps waiting while the snap prepares and prints the new snap id only when that snap is ready to use. How long that takes depends on the file system and on data that is still being uploaded.

Check that the job never stopped

sys9 run box execs inspect <exec-id>
sys9 run box exec builder tail -n 3 /work/progress.log

The exec is still running, and the log keeps growing past the moment of the fork.

Open a box from the fork

sys9 run box create builder-copy --snap <forked-snap-id>
sys9 run box exec builder-copy tail -n 3 /work/progress.log
sys9 run box exec builder-copy ps

builder-copy has the log as it was at the fork, and no loop is running in it. A fork copies files, not processes: the new box starts fresh and does not inherit memory, open files, or connections.

What a fork of a running box includes

  • Writes that the operating system already received are in the snap. Writes racing with the fork may land on either side.
  • Data that an application still holds in its own buffers is not included. Save or flush it first when it matters.
  • A fork covers one file system. Several files changed together by an application are not captured as one transaction.
  • The fork does not run the on_start or on_stop hooks of the running box. A new box runs its own on_start when it wakes.

A database is the usual case where this boundary matters. Test Database Changes on a Copy stops the parent first so that the shutdown hook can leave clean data files.

Several forks at once

You can start several forks from the same box at the same time. Each one captures its own moment and returns when its own snap is ready.

A file transfer and a fork of the same box cannot overlap. Let box cp finish, then fork. Stopping or deleting the box while a fork prepares cancels that fork; it returns an error and leaves no partial snap behind.

Copy the data disk instead

--from-box alone captures the root file system. If the box keeps its data on a Volume, name the mount path to capture that disk:

sys9 run snap fork --from-box builder --volume /state

Back Up and Restore Data builds on this.

Clean up

sys9 run box exec-bg kill <exec-id>
sys9 run box rm builder-copy
sys9 run box rm builder