a3s-box

a3s-box - drive the microVM sandbox

a3s-box runs OCI images inside hardware-isolated microVMs with a Docker-like CLI (verbs mirror Docker). Preflight once: a3s-box info (confirms virtualization + home dir).

Mental model (these cause silent failures)

• Lifecycle: created -> running -> paused -> stopped -> dead.
  • run = create and start. create stops at created -> start it. snapshot restore -> created -> start it.
  • A box dies when its PID 1 exits - it needs a foreground process. run -d alpine runs sh, which exits at once -> dead. Use a long-lived command: run -d nginx, or run -d alpine -- sleep 3600.
  • exec/shell/cp/top/attach need a running box. start accepts only created|stopped|dead. rm removes created/stopped/dead without -f; -f is only for a running/paused box.
• The -- rule: the in-box command goes after --. a3s-box exec <box> -- <cmd> (required); a3s-box run <image> [-- <cmd>] (optional override). Missing it -> error: unexpected argument '...' found.
• exec has a 5-second default timeout - long builds/installs/tests get killed mid-run (and look like a failure). Use --timeout 300 (or --timeout 0 to disable): a3s-box exec --timeout 300 web -- <cmd>.
• Detached boxes need the monitor. run -d prints the id and exits; its health/restart task dies with it. For --restart policies and health checks to fire, run a3s-box monitor in the background first.
• No in-guest localhost by default. A box can't reach its own service on 127.0.0.1 (so --health-cmd 'curl localhost' and in-box curl fail). To make in-guest localhost work, attach a bridge network (recipe below). To check a service from your side, curl the published HOST port (see Ports).
• Ports: publish with -p HOST:GUEST (TCP). But ps's PORTS column and a3s-box port <box> render GUEST -> 0.0.0.0:HOST - the host port to curl is the one after 0.0.0.0:. Read it with a3s-box port <box>.
• Output streams: run -d prints a human Creating box <name> (<id>)... line, the full box id, and (when uncached) image-pull progress - all to stdout; only tracing/WARN/ERROR go to stderr. Don't parse the id from stdout - reference boxes by --name. JSON where offered: inspect, image-inspect, snapshot ls --json, and ps --format json (2.6+ only; on 2.0 use ps --format '{{.ID}} {{.Status}} {{.Names}}').