CLI Reference

A3S Box exposes 55 top-level commands. They are Docker-like commands for a MicroVM runtime, not a promise of Docker CLI parity.

Boxes can be referenced by name, full ID, or a unique short ID prefix.

Command Families

Family	Commands
Lifecycle	`run`, `create`, `start`, `stop`, `restart`, `rm`, `kill`, `pause`, `unpause`, `wait`, `rename`
Execution	`exec`, `attach`, `top`, `shell`
Images	`pull`, `push`, `build`, `images`, `rmi`, `tag`, `image-inspect`, `history`, `image-prune`, `save`, `load`, `commit`
Filesystem	`cp`, `export`, `diff`
Networking	`network`, `port`
Volumes	`volume`
Snapshots	`snapshot`
Compose	`compose`
Observability	`ps`, `logs`, `inspect`, `stats`, `events`, `df`, `audit`
System	`system-prune`, `container-update`, `monitor`, `pool`, `login`, `logout`, `version`, `info`, `help`
TEE	`attest`, `seal`, `unseal`, `inject-secret`

Lifecycle

a3s-box run [OPTIONS] IMAGE [-- CMD...]
a3s-box create [OPTIONS] IMAGE [-- CMD...]
a3s-box start BOX [BOX...]
a3s-box stop BOX [BOX...]
a3s-box restart BOX [BOX...]
a3s-box kill BOX [BOX...]
a3s-box pause BOX [BOX...]
a3s-box unpause BOX [BOX...]
a3s-box wait BOX [BOX...]
a3s-box rename OLD NEW
a3s-box rm [-f] BOX [BOX...]

run pulls if needed, creates state, boots the VM, and either waits for the foreground command or returns after a detached boot. create persists the same configuration but does not boot until start.

Common supported run / create options:

Option	Meaning
`--name NAME`	Assign a stable box name.
`-d`, `--detach`	Run in the background.
`-i`, `--interactive`, `-t`, `--tty`	Keep stdin open and/or allocate a PTY. Detached TTY is rejected.
`--rm`	Remove the box after it exits.
`--cpus N`, `--memory SIZE`	Set boot-time vCPU and memory size.
`-e KEY=VALUE`, `--env-file FILE`	Merge container environment. Inline env overrides env files.
`--entrypoint`, `CMD...`	Override image entrypoint and command.
`-u USER`, `-w DIR`	Run as root, UID, or UID:GID, and set an absolute workdir.
`--hostname`, `--add-host HOST:IP`	Write host identity and static hosts entries inside the guest.
`-v HOST:GUEST[:ro]`	Bind mount or named volume.
`-p HOST:GUEST[/tcp]`	Publish a TCP port.
`--network NAME`	Join an existing A3S bridge network.
`--restart POLICY`	`no`, `always`, `on-failure[:N]`, or `unless-stopped`.
`--health-*`, `--no-healthcheck`	Configure or disable health checks.
`--cap-add`, `--cap-drop`, `--security-opt`, `--privileged`	Configure supported guest security options.
`--tee`, `--tee-simulate`	Enable hardware or simulated TEE flow.

Guarded options such as --device, --gpus, unsupported security labels, unsupported users, invalid workdirs, and unsupported port syntax fail before state is persisted.

Execution

a3s-box exec [OPTIONS] BOX -- CMD [ARG...]
a3s-box exec -it BOX -- /bin/sh
a3s-box attach BOX
a3s-box shell BOX
a3s-box top BOX

exec supports environment overrides, numeric users, root, UID:GID, and absolute workdirs. PTY and non-PTY exec use guest control sockets; missing sockets and stopped boxes report contextual errors.

Images

a3s-box pull [OPTIONS] IMAGE
a3s-box push IMAGE
a3s-box build [OPTIONS] PATH
a3s-box images
a3s-box image-inspect IMAGE
a3s-box history IMAGE
a3s-box tag IMAGE NEW_TAG
a3s-box rmi IMAGE [IMAGE...]
a3s-box image-prune [--force]
a3s-box save -o FILE.tar IMAGE
a3s-box load -i FILE.tar [--tag TAG]
a3s-box commit BOX -t TAG

Important boundaries:

build --platform accepts one target platform. Multi-platform indexes are not implemented.
Dockerfile RUN requires root-capable Linux for isolated chroot execution.
macOS Dockerfile RUN fails by default unless A3S_BOX_UNSAFE_HOST_RUN=1 is set for local experiments.
Unsupported Dockerfile flags fail explicitly.

Networking

a3s-box network create NAME [--subnet CIDR] [--driver bridge] [--isolation none]
a3s-box network ls
a3s-box network inspect NAME
a3s-box network connect NETWORK BOX
a3s-box network disconnect NETWORK BOX
a3s-box network rm [-f] NAME [NAME...]
a3s-box port BOX

Only the bridge driver and none isolation mode are attachable today. strict and custom policies are rejected because packet filtering is not implemented. Live hot-plug is not implemented; connect and disconnect inactive boxes only.

Volumes, Files, and Snapshots

a3s-box volume create NAME
a3s-box volume ls
a3s-box volume inspect NAME
a3s-box volume rm NAME [NAME...]
a3s-box volume prune

a3s-box cp SRC DST
a3s-box export BOX -o FILE.tar
a3s-box diff BOX

a3s-box snapshot create BOX NAME
a3s-box snapshot restore SNAPSHOT --name NEW_BOX
a3s-box snapshot ls
a3s-box snapshot inspect SNAPSHOT
a3s-box snapshot rm SNAPSHOT

Snapshots are not live memory checkpoints; treat them as Box-managed persisted state/filesystem snapshots.

Compose

a3s-box compose -f compose.yaml config
a3s-box compose -f compose.yaml up -d
a3s-box compose -f compose.yaml ps
a3s-box compose -f compose.yaml logs -f
a3s-box compose -f compose.yaml down

Supported keys include image, command, entrypoint, environment, env_file, ports, volumes, depends_on with service_started or service_healthy, networks, dns, tmpfs, working_dir, hostname, extra_hosts, labels, healthcheck, restart, cpus, mem_limit, cap_add, cap_drop, and privileged.

Observability and System

a3s-box ps [-a]
a3s-box logs [-f] [--tail N] BOX
a3s-box inspect BOX
a3s-box stats [--no-stream] [BOX]
a3s-box events [--json]
a3s-box df [--verbose]
a3s-box audit [--action ACTION] [--box BOX] [--outcome success|failure]
a3s-box info
a3s-box version
a3s-box monitor
a3s-box pool start|stop|status
a3s-box system-prune --force

info should be the first diagnostic command on a new host because it reports platform capability and network/TEE boundaries.

CLI Reference

On this page