Fork Storage

This page shows the core run9 storage workflow: Fork & Scale. Prepare one baseline once, capture its file system in a snap, then open parallel boxes from that same starting state.

The same pattern fits several natural jobs:

• multi-agent development from one prepared repo, with boxes such as agent-fix-login, agent-write-tests, and agent-repro-bug
• integration-test sharding from one prepared environment, with boxes such as itest-01 through itest-20
• environment branches such as migration-a, migration-b, and customer-incident, where tools and application files share one root file system

The preparation can be as small as “install two tools” or as large as “clone the repo, install dependencies, and seed test data.”

Actual parallel capacity depends on available org capacity and underlying cloud limits.

What you are building

⌘Copydocker.io/library/node:22-bookworm
               |
               v
         box: app-base
 (repo checkout + dependencies)
               |
               v
       snap: <forked-snap-id>
         /          |           \
        v           v            v
agent-fix-login agent-write-tests agent-repro-bug

Each branch starts from the same file system state. Later changes in one branch do not affect the others.

Prepare a base box

⌘Copysys9 run box create app-base --image docker.io/library/node:22-bookworm
sys9 run box exec app-base -it bash

Inside that shell:

⌘Copy# inside the shell:
apt-get update
apt-get install -y git
npm install -g pnpm
mkdir -p /work
git clone <your-repo-url> /work/your-repo
cd /work/your-repo
pnpm install
ls
exit

Replace <your-repo-url> with the repo URL you actually use. For the smoothest first setup, start with the HTTPS URL for that repo.

Capture that file system in a snap

Fork directly from the prepared box:

⌘Copysys9 run snap fork --from-box app-base

A running box pauses briefly and resumes its existing processes while the snap prepares. The command waits until the new snap is ready, then returns its id. That snap contains the repo checkout and installed dependencies. Preparation time depends on the file system and any data still being uploaded.

Fork captures one file system. A root fork excludes Volumes; use --volume <mount-path> to save one separately. New boxes start fresh processes from the saved files. Application memory, connections, and private buffers are not copied. See Snap for the consistency boundary.

Open parallel agent boxes

⌘Copysys9 run box create agent-fix-login --snap <forked-snap-id>
sys9 run box create agent-write-tests --snap <forked-snap-id>
sys9 run box create agent-repro-bug --snap <forked-snap-id>
sys9 run box exec agent-fix-login --workdir /work/your-repo git status
sys9 run box exec agent-write-tests --workdir /work/your-repo pnpm test -- login
sys9 run box exec agent-repro-bug --workdir /work/your-repo printenv HOME

At this point:

• all three boxes inherited the same repo checkout and dependencies
• each box can change files, install debug tools, and run commands independently
• later changes in one box do not affect the others

That is the main snap-fork workflow in run9: version the whole environment once, then branch it for parallel work.

The same snap can feed test shards

If the baseline already contains your repo, dependencies, and test data, the same snap can also open itest-01 through itest-20. That avoids reinstalling the same environment for each shard and keeps every shard on the same starting state.

Keep the baseline clean

Keep <forked-snap-id> if you expect to open more branches later. If you change the parent box again and want a new baseline, fork a new snap from that newer state.

The shared part is only the starting state. Each new box becomes its own isolated branch.