Quick start

run9 gives you a remote box that wakes when you use it and sleeps when it is idle. You can use it as a plain remote box, but the quickest way to understand what makes run9 distinctive is to see its main pattern end to end: Fork & Scale. Prepare one parent box, fork it into a snap, then open new boxes from that same baseline.

If this is the first machine you use with run9, finish Install and Authenticate first. Come back here after run9 --version and run9 auth whoami both work.

By the end of this page, you will have one parent box named base, one file copied into it, one forked snap, and one working branch box named dev created from that saved state.

What you are building

⌘Copylocal hello.txt
       |
       v
   box: base
       |
       v
snap: <forked-snap-id>
       |
       v
   box: dev

The point of this flow is simple: prepare something once, then keep working in a fresh branch that starts from that exact state.

Create a parent box

⌘Copyrun9 box create base

That box is your writable parent workspace. There is no separate boot step.

Put one file into that parent

⌘Copyprintf 'hello from run9\n' > ./hello.txt
run9 box exec base mkdir -p /work
run9 box cp ./hello.txt base:/work/hello.txt

box exec wakes the box for the mkdir -p /work step. box cp then uploads the file into that same box.

Fork that prepared state

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

⌘Copyrun9 box stop base
run9 snap fork --from-box base

The command returns a snap id. That snap now captures the prepared file system state, including /work/hello.txt.

Open a working branch

Create a new box from the forked snap, then verify that the inherited file is there:

⌘Copyrun9 box create dev --snap <forked-snap-id>
run9 box exec dev wc -l /work/hello.txt
run9 box exec dev uname -a

If wc -l shows the file and uname -a prints system information, the branch box is ready and the fork worked.

That one fork is the main run9 pattern: keep a reusable parent state, then branch off isolated boxes whenever you want a fresh workspace.

From the same snap, you could later open agent-fix-login, itest-01, or migration-a. The point is not only that run9 can save one state. It can turn one prepared state into parallel boxes for different jobs.

Output modes

run9 defaults to readable terminal output: short confirmations, tables, summaries, and hints.

Use JSON when a script needs the full object:

⌘Copyrun9 --json box inspect dev
run9 --output json box ls

Control ANSI color in text output when needed:

⌘Copyrun9 --color never box ls

Commands that stream remote output, such as box exec, keep the stream as plain output and do not support --json.

Next steps

• Fork Storage for turning one prepared box into parallel boxes for agents, test shards, and other isolated work
• Execute Commands for one-off commands that already fit on one line
• Interactive Shell for package installs, editing files, and trial-and-error work inside one live session
• Long-running Task for commands that should keep running after you close the current terminal
• Access via SSH for the same box access model through a standard ssh client or one-off remote commands
• File Transfer for moving project files and artifacts in or out