Every command.
A little less guesswork.

Launch isolated microVMs for AI agents.

Launch isolated microVMs for AI agents.

The box comes first, always: `terra [BOX]` starts it, or attaches if it is already up. A verb after the box names one operation on it instead - `terra dev stop`, `terra dev sync :/etc/x .` - and every verb defaults to this directory's only box. With a box already up and neither a terminal to attach from nor `-d`, terra exits 125.

Native sandboxes with built-in policies always isolate the VM and network broker.

Usage: terra [OPTIONS] [BOX] [-- <CMD>...] [COMMAND]

Commands:
  setup        Set up a box for this directory: read a recipe, pin it, build the guest filesystem, and run `on_create`. Safe to run again
  exec         Run a command in a running box, on a terminal of its own - a second process beside the workload, not a second view of it
  sync         Synchronize files and directories between the host and a running box
  logs         Show a box's host diagnostics, rotated as it grows. `--diagnostics` shows guest VM diagnostics instead; both are replayed after a failed boot. The workload's terminal goes to the session - attach to the box to see it live
  sessions     List the clients attached to the box's session: the ids `terra <box> detach` takes, and the terminal size each one reported. The shared view fits the tightest client, so one that stopped reading keeps it small until it is detached
  detach       Drop one attached client of the box's session - or every one of them. The client's connection is closed and its terminal restored, as if the detach key had been pressed
  show         Print the fully-resolved config a boot would use: the box's pinned recipe, or - for a box not set up yet, or a recipe named by path - the recipe that would be pinned
  ls           List this directory's boxes and what state each is in - or, with `--all`, every box on this machine
  stop         Stop a running box: the guest runs `pre_stop`, then the VM exits
  storage      The box's storage - its guest filesystem and volume images
  rm           Throw a box away: its guest filesystem, volumes, logs and sockets. The recipe is kept, so `terra <box> setup` can build it again from scratch
  completions  Output shell completion code for the specified shell
  help         Print this message or the help of the given subcommand(s)

Arguments:
  [BOX]
          Box name. Default: this directory's only box

  [CMD]...
          Command to run instead of the recipe's `workload:`, after `--`. argv is passed literally to the guest exec, so use `-- sh -c '…'` for a shell line

Options:
      --root
          Run the workload as root instead of the default `terri` (uid 1000)

  -d, --detach
          Run headless after the guest agent becomes ready, before startup hooks finish. Boot fails if the agent is not ready within 60 seconds

      --foreground
          Run the VM in the foreground - for a service manager (systemd), which wants the VM as its own child and has no terminal to join

      --agent-timeout <SECS>
          Give up after this many seconds if the agent has not answered yet. Bounds the client connection wait, never hooks or command runtime. Default: wait while the box runs. New VMs separately require guest agent readiness within 60 seconds

      --project <DIR>
          The project directory whose boxes to address (default: the current one)

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

EXAMPLES:
    terra dev                   Start this directory's box `dev`, or attach
    terra dev exec -- ls        Run a command in the running box
    terra ./pi-dev.yaml setup   Set up a box from a recipe
    terra dev logs -f           Follow the box's log

Set up a box for this directory: read a recipe, pin it, build the guest filesystem, and run `on_create`. Safe to run again

Set up a box for this directory: read a recipe, pin it, build the guest filesystem, and run `on_create`. Safe to run again.

The box before it may be a recipe *path* as well as a name, the box then taking the file's stem: `terra ./pi-dev.yaml setup`.

Usage: terra [BOX] setup [OPTIONS]

Options:
      --trust-recipe
          Pin the recipe without asking, even when a guest could have written it. Required when there is no terminal to ask on

      --rebuild
          Rebuild the guest filesystem from scratch, run `on_create` again, and remove the volume images the recipe no longer names

      --dry-run
          Run every refusal this setup would raise and stop before it changes anything: nothing is pinned, no filesystem is built, no hook runs.
          
          Exits 0 if the setup would go through, non-zero with the refusal if it would not - so a CI step is `terra <box> setup --dry-run`. The other two flags decide what a setup *does*, which is the half this skips, so neither can be written alongside it.

      --project <DIR>
          The project directory whose boxes to address (default: the current one)

  -h, --help
          Print help (see a summary with '-h')

Run a command in a running box, on a terminal of its own - a second process beside the workload, not a second view of it

Run a command in a running box, on a terminal of its own - a second process beside the workload, not a second view of it.

Runs as whoever the workload runs as; `--root` runs it as root instead. That is the difference from a `sudo:` entry, which hands the same power to the workload permanently.

Its exit status is this command's.

Usage: terra [BOX] exec [OPTIONS] -- <CMD>...

Arguments:
  <CMD>...
          The command to run, after `--`. argv is passed literally to the guest exec, so use `-- sh -c '…'` for a shell line

Options:
      --root
          Run as root instead of the workload's own user

  -t, --tty
          Give the command a terminal even when terra was not started at one - for a script driving something that only works on a PTY

  -T, --no-tty
          Give the command pipes even when terra was started at a terminal, so its output is exactly what a redirect would capture

  -w, --workdir <DIR>
          Working directory inside the box

  -e, --env <KEY[=VALUE]>
          Environment variables for the command (KEY=VALUE, or KEY to inherit from the host)

      --agent-timeout <SECS>
          Give up after this many seconds if the agent has not answered yet. Bounds the client connection wait, never hooks or command runtime. Default: wait while the box runs. New VMs separately require guest agent readiness within 60 seconds

      --project <DIR>
          The project directory whose boxes to address (default: the current one)

  -h, --help
          Print help (see a summary with '-h')

Synchronize files and directories between the host and a running box

Synchronize files and directories between the host and a running box.

The guest endpoint is prefixed with `box:` or `:` (e.g. `box:/app/` or `:/app/`). Exactly one endpoint must be a guest endpoint.

Usage: terra [BOX] sync [OPTIONS] <SRC> <DST>

Arguments:
  <SRC>
          Source path. Prefix with 'box:' or ':' for the guest endpoint

  <DST>
          Destination path. Prefix with 'box:' or ':' for the guest endpoint

Options:
      --delete
          Remove destination entries that do not exist on the source (directories only)

      --checksum
          Compare file contents by SHA-256 digest instead of size and timestamp

      --dry-run
          Preview transfers and deletions; downloads create temporary name probes

      --agent-timeout <SECS>
          Give up after this many seconds if the agent has not answered yet. Bounds the client connection wait, never hooks or command runtime. Default: wait while the box runs. New VMs separately require guest agent readiness within 60 seconds

      --project <DIR>
          The project directory whose boxes to address (default: the current one)

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
    terra dev sync ./src/ box:/app/           Sync host ./src/ into guest /app/
    terra dev sync box:/app/output/ ./output/ Sync guest output into host
    terra dev sync --delete ./src/ :/app/     Sync and delete destination extras
    terra dev sync --checksum ./src/ :/app/   Compare file contents using SHA-256
    terra dev sync --dry-run ./src/ :/app/    Preview planned transfers and deletions

Show a box's host diagnostics, rotated as it grows. `--diagnostics` shows guest VM diagnostics instead; both are replayed after a failed boot. The workload's terminal goes to the session - attach to the box to see it live

Show a box's host diagnostics, rotated as it grows. `--diagnostics` shows guest VM diagnostics instead; both are replayed after a failed boot. The workload's terminal goes to the session - attach to the box to see it live

Usage: terra [BOX] logs [OPTIONS]

Options:
  -f, --follow         Follow the log as it grows
  -n, --tail <LINES>   Number of lines of history from the end of the log to print before following
      --diagnostics    Show guest VM diagnostics instead of Terra's host log
      --project <DIR>  The project directory whose boxes to address (default: the current one)
  -h, --help           Print help

List the clients attached to the box's session: the ids `terra <box> detach` takes, and the terminal size each one reported. The shared view fits the tightest client, so one that stopped reading keeps it small until it is detached

List the clients attached to the box's session: the ids `terra <box> detach` takes, and the terminal size each one reported. The shared view fits the tightest client, so one that stopped reading keeps it small until it is detached

Usage: terra [BOX] sessions [OPTIONS]

Options:
      --json                  Output machine-readable JSON array of sessions
      --agent-timeout <SECS>  Give up after this many seconds if the agent has not answered yet. Bounds the client connection wait, never hooks or command runtime. Default: wait while the box runs. New VMs separately require guest agent readiness within 60 seconds
      --project <DIR>         The project directory whose boxes to address (default: the current one)
  -h, --help                  Print help

Drop one attached client of the box's session - or every one of them. The client's connection is closed and its terminal restored, as if the detach key had been pressed

Drop one attached client of the box's session - or every one of them. The client's connection is closed and its terminal restored, as if the detach key had been pressed

Usage: terra [BOX] detach [OPTIONS] [ID]

Arguments:
  [ID]  The client id `terra <box> sessions` printed

Options:
      --all                   Detach every attached client instead of one by id
      --agent-timeout <SECS>  Give up after this many seconds if the agent has not answered yet. Bounds the client connection wait, never hooks or command runtime. Default: wait while the box runs. New VMs separately require guest agent readiness within 60 seconds
      --project <DIR>         The project directory whose boxes to address (default: the current one)
  -h, --help                  Print help

Print the fully-resolved config a boot would use: the box's pinned recipe, or - for a box not set up yet, or a recipe named by path - the recipe that would be pinned

Print the fully-resolved config a boot would use: the box's pinned recipe, or - for a box not set up yet, or a recipe named by path - the recipe that would be pinned.

For review only - `env:` values are printed as a placeholder unless `--with-env-values`, and paths as the absolute ones they resolved to on this machine, so it is not a recipe you can pin back.

Usage: terra [BOX] show [OPTIONS]

Options:
      --with-env-values
          Print the `env:` values too, instead of a placeholder. They are secrets often enough to be worth asking for: this output is made to be redirected to a file or pasted into a bug report

      --json
          Output machine-readable JSON instead of YAML

      --project <DIR>
          The project directory whose boxes to address (default: the current one)

  -h, --help
          Print help (see a summary with '-h')

List this directory's boxes and what state each is in - or, with `--all`, every box on this machine

List this directory's boxes and what state each is in - or, with `--all`, every box on this machine

Usage: terra ls [OPTIONS]

Options:
      --all
          Every box on this machine instead, each with the directory it belongs to

      --state <STATE>
          Include only these states; repeat or separate with commas to match any

          Possible values:
          - running
          - setting_up
          - stopped
          - needs_setup: A root image exists, but setup did not finish for the pinned recipe
          - not_created
          - gone:        State remains, but the project directory is gone

  -q, --quiet
          Print only box names, one per line. With --all, names may repeat across projects

      --tsv
          One box per line - state, name, directory, files - separated by tabs, with no prose around them. This is the format scripts may rely on; the human listing is prose and may change

      --json
          Output machine-readable JSON array of boxes

      --project <DIR>
          The project directory whose boxes to address (default: the current one)

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
    terra ls --state running --quiet         Print running box names
    terra ls --state needs_setup,not_created Find boxes that need setup
    terra ls --all --state running --json    Inspect running boxes across projects

Stop a running box: the guest runs `pre_stop`, then the VM exits

Stop a running box: the guest runs `pre_stop`, then the VM exits

Usage: terra [BOX] stop [OPTIONS]

Options:
  -t, --timeout <SECS>  How long to wait in seconds for the guest to shut down before the VM is killed [default: 65]
      --project <DIR>   The project directory whose boxes to address (default: the current one)
  -h, --help            Print help

The box's storage - its guest filesystem and volume images

The box's storage - its guest filesystem and volume images

Usage: terra [BOX] storage [OPTIONS] <COMMAND>

Commands:
  show    List the box's images: what each is sized to, what it costs on disk, and which the recipe no longer names
  export  Write the box's images to one file, to be imported into a box set up from the same recipe on another machine
  import  Replace the box's images with those in a file `export` wrote. The box must be set up already, and must not be running. After a root-image import, `terra BOX setup` finishes it before the box starts
  prune   Remove the volume images the recipe no longer names. Their data goes with them
  help    Print this message or the help of the given subcommand(s)

Options:
      --project <DIR>  The project directory whose boxes to address (default: the current one)
  -h, --help           Print help

List the box's images: what each is sized to, what it costs on disk, and which the recipe no longer names

List the box's images: what each is sized to, what it costs on disk, and which the recipe no longer names

Usage: terra [BOX] storage show [OPTIONS]

Options:
      --json           Output machine-readable JSON
      --project <DIR>  The project directory whose boxes to address (default: the current one)
  -h, --help           Print help

Write the box's images to one file, to be imported into a box set up from the same recipe on another machine

Write the box's images to one file, to be imported into a box set up from the same recipe on another machine.

The images only - the recipe is what makes a box, and it travels with the project. The box must not be running.

Usage: terra [BOX] storage export [OPTIONS] <FILE>

Arguments:
  <FILE>
          The artifact's path on the host

Options:
      --project <DIR>
          The project directory whose boxes to address (default: the current one)

  -h, --help
          Print help (see a summary with '-h')

Replace the box's images with those in a file `export` wrote. The box must be set up already, and must not be running. After a root-image import, `terra BOX setup` finishes it before the box starts

Replace the box's images with those in a file `export` wrote. The box must be set up already, and must not be running. After a root-image import, `terra BOX setup` finishes it before the box starts

Usage: terra [BOX] storage import [OPTIONS] <FILE>

Arguments:
  <FILE>  The artifact's path on the host

Options:
      --project <DIR>  The project directory whose boxes to address (default: the current one)
  -h, --help           Print help

Remove the volume images the recipe no longer names. Their data goes with them

Remove the volume images the recipe no longer names. Their data goes with them

Usage: terra [BOX] storage prune [OPTIONS]

Options:
      --project <DIR>  The project directory whose boxes to address (default: the current one)
  -h, --help           Print help

Throw a box away: its guest filesystem, volumes, logs and sockets. The recipe is kept, so `terra <box> setup` can build it again from scratch

Throw a box away: its guest filesystem, volumes, logs and sockets. The recipe is kept, so `terra <box> setup` can build it again from scratch

Usage: terra [BOX] rm [OPTIONS]

Options:
      --purge           Remove the recipe too, leaving nothing of the box at all
      --force           Remove it even while a VM is running: a graceful stop is asked for first, but the box is removed either way
  -t, --timeout <SECS>  How long to wait in seconds for that graceful stop. Only means anything with `--force`, so clap refuses it on its own [default: 65]
      --project <DIR>   The project directory whose boxes to address (default: the current one)
  -h, --help            Print help

Output shell completion code for the specified shell

Output shell completion code for the specified shell

Usage: terra completions [OPTIONS] <SHELL>

Arguments:
  <SHELL>
          Target shell for completions
          
          [possible values: bash, elvish, fish, powershell, zsh]

Options:
      --project <DIR>
          The project directory whose boxes to address (default: the current one)

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
    source <(terra completions bash)
    eval "$(terra completions zsh)"