Get Started
FORK & SCALE

Boost First Runs

Make the first command in every new box start as fast as a repeat run.

In a fresh box, the first pnpm test is noticeably slower than the second. The first run has to fetch every file the command reads: the executable, its libraries, the modules it loads. After that the files are close by and the command is fast.

That is a small cost for one box. It adds up when you start twenty test shards or a new agent box for every task, because each of them is fresh and each pays it again.

You can pay it once instead. Record the command on your baseline, and run9 keeps exactly the data that command reads ready where your boxes run. Every box you start from that baseline then runs the command warm from its first second, with no extra flag per box or per command. The feature is called prewarm.

What you are building

snap: <baseline-snap-id>  ── record "pnpm test" once ──>  profile: repo-tests
        |
        +── box: itest-01   first "pnpm test" starts warm
        +── box: itest-02   first "pnpm test" starts warm
        +── snap: <later-fork>
                  |
                  +── box: itest-03   still starts warm

Record the command once

Take the snap you start your boxes from, for example the one from Run Parallel Boxes from One Setup, and record the command you want to be fast:

sys9 run prewarm record repo-tests --snap <baseline-snap-id> -- /bin/sh -lc 'cd /work/your-repo && pnpm test -- login'

repo-tests is a name you choose. Everything after -- is the command. run9 runs it once in a temporary box, shows its output, and removes that box afterwards. When the last line reports the profile as ready, you are done.

Record what your boxes really run first. If that is several commands, put them in one script and record the script.

The snap must be a saved one, not the disk a box is currently using. If your setup lives in a box, fork it first:

sys9 run snap fork --from-box app-base

Start boxes as usual

There is nothing to turn on:

sys9 run box create itest-01 --snap <baseline-snap-id>
sys9 run box exec itest-01 --workdir /work/your-repo pnpm test -- login

When a command was served from the recording, the CLI prints one short Prewarm repo-tests: ... line after its output, with how much data came from it. If you never see that line, check that the box was started from the recorded snap or a fork of it, and that prewarm inspect shows the recording as ready and enabled.

Snaps you fork later from the baseline, and boxes started from those, are covered too. Files that a later fork added or rewrote are simply read the normal way.

Servers and other commands that never finish

A recording stops the command after one minute by default and keeps everything it read up to then. That is what you want for a server or a watcher: let it start, then cut it off.

sys9 run prewarm record api-start --snap <baseline-snap-id> --max-runtime 30s -- /work/your-repo/bin/server

--max-runtime accepts 1s to 12h. Raise it when the command you record needs longer than a minute. Ctrl+C ends the command early and still saves what was collected.

See whether it is used

sys9 run prewarm ls
sys9 run prewarm inspect repo-tests

inspect shows how often the recording was used and when it was last used, so you can tell whether your boxes actually benefit. It also shows its size and whether it is installed everywhere your boxes run; prewarm enable retries an installation that failed.

When the baseline changes

Small changes need nothing: a fork of the baseline keeps using the recording.

After a big change, such as a dependency upgrade that replaces most of what the command reads, record again on the new snap:

sys9 run prewarm record repo-tests-v2 --snap <new-baseline-snap-id> -- /bin/sh -lc 'cd /work/your-repo && pnpm test -- login'

Boxes started from the new snap use the new recording; boxes from the old one keep using the old.

To replace a recording on the same snap, remove it and record again. To switch one off without removing it, disable it:

sys9 run prewarm rm repo-tests
sys9 run prewarm disable repo-tests

Things to know

  • One snap holds one recording. For a second command on the same snap, record a script that runs both.
  • A snap cannot be removed while a recording is attached to it. Remove the recording first.
  • A command that fails still produces a usable recording, and prewarm record returns the command’s exit code.
  • This prepares data, not machines. It does not start boxes ahead of time.
  • Recorded data is installed only on hosts that serve your org.