Get Started
GETTING STARTED

Quick start

Prepare one box, fork it into a snap, and open a working branch from that saved state.

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 sys9 run --version and sys9 run 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

local 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

sys9 run box create base

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

Put one file into that parent

printf 'hello from run9\n' > ./hello.txt
sys9 run box exec base mkdir -p /work
sys9 run 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

Fork directly from the parent, including while it is running:

sys9 run snap fork --from-box base

The parent pauses briefly, then continues while the snap prepares. The command returns a snap id only when the new snap is ready, with 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:

sys9 run box create dev --snap <forked-snap-id>
sys9 run box exec dev wc -l /work/hello.txt
sys9 run 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

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

Use JSON when a script needs the full object:

sys9 run --json box inspect dev
sys9 run --output json box ls

Control ANSI color in text output when needed:

sys9 run --color never box ls

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

Where to go next

Pick the page that matches what you want to do.

Work in one box:

Run many boxes from one setup:

Look after data and keys: