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

⌘Copysys9 run box create [box-id]
sys9 run box ls
sys9 run box inspect <box-id>
sys9 run box exec <box-id> [flags] <command...>
sys9 run box exec-bg <box-id> [flags] <command...>
sys9 run box execs ls <box-id>
sys9 run box execs inspect <exec-id>
sys9 run box cp <source> <target>
sys9 run box file ls|stat|cat|get <box-id> ...
sys9 run box stop <box-id>
sys9 run 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:

⌘Copysys9 run --json box inspect my-box
sys9 run --output json box ls

box exec and box file cat are stream commands. They forward raw output, so they reject --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.