Get Started
REFERENCE

Box

Reference for box creation, Volumes, updates, states, listing, and deletion.

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

sys9 run box create [box-id]
sys9 run box ls
sys9 run box inspect <box-id>
sys9 run box update <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 secrets ls|create|update|rm <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, its Storage table, and a next command.
  • box ls prints a compact table or a clear empty state.
  • box inspect prints a compact summary, a Files link for read-only file access, its Outbound IP, and a Storage table with every disk of the box.
  • box stop, box rm, and box cp print OK: confirmations.

Use JSON for automation:

sys9 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

Choose at most one source for the root file system:

  • --image <image-ref> starts from a container image.
  • --snap <snap-id> starts from a snap in the current project.
  • --shared-snap <name> starts from a Shared Snap; add --shared-snap-version <n> for one exact version.

Without a source, run9 uses its default image.

Other options:

  • --shape 1c2g, 2c4g, 4c8g, 8c16g, or 8c32g. The default is 1c2g. Warm hosts do not serve 8c32g, so starting one may wait for a new host.
  • --volume <spec> adds a Volume. Repeat it for up to nine.
  • --network normal or managed. The default is normal; managed is what Project Secrets need.
  • --description <text>
  • --label key=value

Volumes

--volume gives the box an extra persistent disk at a fixed path. Volumes are chosen at creation and cannot be changed later.

--volume /state                              empty Volume
--volume /state,uid=1000,gid=1000,mode=0700  empty Volume with an owner and mode
--volume /state,from=<snap-id>               Volume that starts from existing data

Volume has the rules for paths, owners, sources, and lifecycle.

Update

sys9 run box update my-box --shape 2c4g
sys9 run box update my-box --network managed
sys9 run box update my-box --label team=web --label purpose=ci
sys9 run box update my-box --clear-labels
  • --label replaces the whole label set. --clear-labels removes all labels. Labels also decide which label-limited Project Secrets the box can use; a change applies to new HTTPS connections within seconds.
  • --description changes the description.
  • A new --network value applies the next time the box starts. A box that is awake keeps its current mode until box stop.

Filter the list

sys9 run box ls --state running
sys9 run box ls --label team=web

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.

Inside a box

Every box is its own virtual machine with its own kernel, not a shared container. Commands run as root unless --user says otherwise, and FUSE file systems can be mounted inside a box.

A box reaches public internet addresses from its project’s outbound IP. Private and local network ranges are not reachable from a box.