Box

A box is the main runtime object in run9. It is the thing you create, exec into, copy files to, and optionally freeze into a snap.

Commands

⌘Copyrun9 box create [box-id]
run9 box ls
run9 box inspect <box-id>
run9 box exec <box-id> [flags] <command...>
run9 box exec-bg <box-id> [flags] <command...>
run9 box execs ls <box-id>
run9 box execs inspect <exec-id>
run9 box cp <source> <target>
run9 box stop <box-id>
run9 box rm <box-id>

Add -- only when the remote command itself starts with flag-like tokens and you need to stop local flag parsing.

Output

Default output is text for humans:

• box create prints the new box id, state, shape, source, and a next command.
• box ls prints a compact table or a clear empty state.
• box inspect prints a compact summary.
• box stop, box rm, and box cp print OK: confirmations.

Use JSON for automation:

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

box exec is a stream command. It forwards remote stdout and stderr, so it rejects --json.

Create options

• --shape 1c2g, 2c4g, 4c8g, or 8c16g
• --image <image-ref>
• --snap <snap-id>
• --description <text>
• --label key=value

--image and --snap choose the initial file system. If no source is passed, run9 chooses the default source image.

States

• ready: the box exists, but it is not awake yet.
• idle: the box is awake and waiting for the next exec or file transfer.
• running: an exec or file transfer is active.
• error: run9 hit a system problem. Treat this as platform trouble, not a normal app exit.

Boxes wake when used and can sleep when idle. box stop is for an immediate quiet point or cleanup, not a required daily step.