Get Started
TUTORIAL

Fork Storage

Turn one prepared baseline into parallel boxes for agents, test shards, and other isolated work.

This page shows the core run9 storage workflow: Fork & Scale. Prepare one baseline once, freeze it into 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 the whole stack should fork together

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.

Prepare a base box

run9 box create app-base --image docker.io/library/node:22-bookworm
run9 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.

Freeze that file system into a snap

Stop the box before forking so the file system is quiet:

run9 box stop app-base
run9 snap fork --from-box app-base

The command returns a snap id. That snap now represents the prepared baseline, including the repo checkout and installed dependencies.

Open parallel agent boxes

run9 box create agent-fix-login --snap <forked-snap-id>
run9 box create agent-write-tests --snap <forked-snap-id>
run9 box create agent-repro-bug --snap <forked-snap-id>
run9 box exec agent-fix-login --workdir /work/your-repo git status
run9 box exec agent-write-tests --workdir /work/your-repo pnpm test -- login
run9 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, stop it and fork a new snap from that newer state.

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