Keep Data Separate from the Environment

A box that has been working for a while holds two different things. One is the environment: tools, a repo checkout, installed dependencies. The other is what built up while it worked: an agent’s conversation history, credentials it was handed, caches, results.

You rarely want to copy both together.

• When you fork the box to start ten more agents, you want the environment and none of the first agent’s history.
• When you replace the environment with a newer image, you want to keep the history.

If everything sits on one file system, every fork carries everything. Give the data its own disk, a Volume, and the two can be copied, kept, and replaced independently.

What you are building

⌘Copybox: agent-1
  /        environment   ── fork ──> snap ──> box: agent-2, agent-3, ...
  /state   data             (stays with agent-1)

Create the box with a data disk

⌘Copysys9 run box create agent-1 --volume /state

/state is now a separate persistent disk inside the box. If the flag is reported as unknown, update the CLI.

If your processes do not run as root, hand the directory to their user when you create the box:

⌘Copysys9 run box create agent-1 --volume /state,uid=1000,gid=1000,mode=0700

Put the data there

Point whatever should not travel with the environment at that directory: the agent’s home or session directory, a database, a cache.

⌘Copysys9 run box exec agent-1 /bin/sh -lc 'echo "session 1" > /state/notes.txt'

From inside the box it is an ordinary directory. box exec, box cp, and box file all see it at /state, and it survives box stop, sleep, and every later wake-up like the rest of the box.

Copy the environment without the data

Install tools and prepare the repo on the root file system as usual, then fork:

⌘Copysys9 run snap fork --from-box agent-1
sys9 run box create agent-2 --snap <forked-snap-id> --volume /state
sys9 run box exec agent-2 ls -la /state

agent-2 has every tool agent-1 had, and an empty /state of its own. A fork of the environment never includes what is on a Volume, so there is nothing to clean up before you fork and no session data leaks into the copies.

Pass --volume /state for each new box. Without it the new box has no /state disk at all, because the fork does not carry the mount either.

What this buys you later

• Checkpoints of the data alone. Back Up and Restore Data saves /state at a point in time and brings it back in a new box.
• A newer environment for the same data. The same page shows how to move /state to a box built from a different image.
• Leaner baselines. The snap you fan out from holds tools, not gigabytes of history.

Plan the layout up front

Disks are chosen when the box is created. A box can have up to nine, and they cannot be added, removed, or moved afterwards. box rm removes the box together with its disks.

Volume has the full rules.