CLI Reference

A3S Box exposes 56 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

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...]
a3s-box prune --force          # remove all created/stopped/dead boxes (alias: container-prune)

prune is the box-only counterpart to system-prune: it removes every created, stopped, and dead box in one call (Docker container prune). Running and paused boxes are never touched, and it requires --force.

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:

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   # copy-on-write fork (overlay)
a3s-box snapshot ls
a3s-box snapshot inspect SNAPSHOT
a3s-box snapshot rm SNAPSHOT [--force]
a3s-box snapshot prune --keep N                    # bound disk: keep the N newest

Snapshots are not live memory checkpoints; treat them as Box-managed persisted state/filesystem snapshots. snapshot restore is copy-on-write: the restored box shares the snapshot's rootfs as a read-only overlay lower with its own upper, so forking a warmed snapshot is near-instant and space-cheap (this is what the SDK's pipeline API forks per step). Because a restored box keeps referencing its snapshot, snapshot rm / prune refuse to delete a snapshot still in use by a box — pass --force to override.

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.

Warm Pool and Snapshot-Fork

The warm pool keeps sandboxes pre-booted and serves them over a Unix socket, so a request runs in an already-warm microVM instead of paying a cold boot.

a3s-box pool start --image alpine:latest --size 8
a3s-box pool start --image alpine:latest --size 8 --snapshot-fork   # CoW fill
a3s-box pool run alpine:latest -- echo hi
a3s-box pool status
a3s-box pool stop

--snapshot-fork is native Copy-on-Write microVM cloning: the pool cold-boots one template, snapshots its file-backed guest RAM plus KVM vCPU and virtio device state, then restores the rest of the pool from that snapshot. Each fork maps the template RAM MAP_PRIVATE and pays only for the pages it dirties. On a /dev/kvm host this is roughly 4× faster than a cold boot per fork and completes 100 forks in under ~1 s (~8 ms amortized each). The same mechanism is reachable below the pool through the KRUN_SNAPSHOT_MEM_FILE, KRUN_SNAPSHOT_SOCK, and KRUN_RESTORE_FROM environment variables. See Configuration for the per-VM config fields.