Get Started
FORK & SCALE

Run Parallel Boxes from One Setup

Set up a repo and its dependencies once, then start as many identical boxes as you need for agents, test shards, or experiments.

Three agents working on the same repo, or twenty test shards, all need the same checkout, the same dependencies, and the same tools. Installing all of that in every box costs minutes each time, and the boxes slowly drift apart.

In run9 you set the environment up once, save that state as a snap, and start every box from it. Each box is a full, independent copy from its first second. This is the Fork & Scale pattern.

It 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

docker.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.

Set the environment up once

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

Inside that shell:

# 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.

Save that state as a snap

Fork directly from the prepared box:

sys9 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.

Start parallel boxes from it

sys9 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.

Next steps