Quick Start

This guide uses only the core CLI path. Run commands from a host where a3s-box info reports a usable VM backend.

1. Install

# macOS / Linux through the Homebrew tap
brew install a3s-lab/tap/a3s-box

# Or build from source
git clone https://github.com/AI45Lab/Box.git
cd Box/src
cargo build --release

On Windows, use the Windows release package and enable the native WHPX backend:

Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform

Check the host:

a3s-box version
a3s-box info

info is intentionally important: it reports the host platform, VM backend, control channel, bridge backend, published-port support, and TEE availability.

2. Run a command

a3s-box run --name hello alpine:latest -- echo "hello from a3s-box"

This pulls the image if needed, prepares a rootfs, boots a MicroVM, runs the command, captures output, and stops the box.

3. Start an interactive shell

a3s-box run -it --name dev alpine:latest -- /bin/sh

For a running box:

a3s-box exec -it dev -- /bin/sh

4. Run a detached service

a3s-box run -d --name web --cpus 2 --memory 1g -p 8080:80 nginx:alpine

a3s-box ps
a3s-box port web
a3s-box logs -f web

Published ports support TCP mappings in host_port:guest_port[/tcp] form. UDP, host-IP binds, shorthand, and ranges are rejected.

5. Execute and inspect

a3s-box exec web -- nginx -v
a3s-box stats --no-stream web
a3s-box inspect web
a3s-box top web

Use --user, --workdir, and --env on exec when the image supports them:

a3s-box exec -u root -w /tmp -e DEBUG=1 web -- sh -c 'id && pwd && env | grep DEBUG'

6. Stop and remove

a3s-box stop web
a3s-box wait web
a3s-box rm web

Use rm -f only when you intentionally want to force cleanup.

7. Use a named volume

a3s-box volume create data
a3s-box run -d --name store -v data:/data alpine:latest -- sleep 3600
a3s-box cp ./local.txt store:/data/local.txt
a3s-box exec store -- ls -la /data
a3s-box rm -f store
a3s-box volume rm data

8. Use a bridge network

a3s-box network create backend --subnet 10.89.0.0/24
a3s-box run -d --name api --network backend -p 8080:80 alpine:latest -- sleep 3600
a3s-box network inspect backend
a3s-box network rm --force backend

Platform boundary:

Linux bridge uses passt and reports outbound NAT support.
macOS bridge uses netproxy for peer networking and published TCP ports; bridge outbound NAT is unsupported.
Use default TSI mode when a macOS workload needs outbound internet access.

9. Build a simple image

# Dockerfile
FROM scratch
COPY hello.txt /hello.txt
CMD ["cat", "/hello.txt"]

echo hello > hello.txt
a3s-box build -t hello:local .
a3s-box run --rm hello:local

For Dockerfile RUN, use root-capable Linux. macOS rejects RUN by default to avoid silently running build steps on the host.

10. Try Compose subset

services:
  worker:
    image: alpine:latest
    command: ["sleep", "3600"]
    environment:
      A3S_EXAMPLE: "1"

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 down

Clean Up

a3s-box system-prune --force
a3s-box image-prune --force
a3s-box volume prune --force

Quick Start

On this page