# macOS (Apple Silicon)
brew install a3s-lab/tap/a3s-box

# Linux / macOS (direct download)
curl -fsSL https://github.com/A3S-Lab/Box/releases/latest/download/install.sh | sh

a3s-box version

# Interactive shell
a3s-box run -it alpine:latest -- /bin/sh

# Detached background box
a3s-box run -d --name web nginx:alpine

# With resource limits
a3s-box run -d --name worker \
  --cpus 4 --memory 2g \
  --timeout 3600 \
  my-image:latest

# List running boxes
a3s-box ps

# List all (including stopped)
a3s-box ps -a

# Stop / start / restart
a3s-box stop web
a3s-box start web
a3s-box restart web

# Force remove
a3s-box rm -f web

# Run a command
a3s-box exec my-box -- ls /app

# Interactive shell
a3s-box exec -it my-box -- /bin/bash

# With env var and working directory
a3s-box exec -e DEBUG=1 -w /app my-box -- ./run.sh

a3s-box logs my-box
a3s-box logs -f my-box           # follow
a3s-box logs --tail 100 my-box   # last 100 lines
a3s-box logs -t my-box           # with timestamps

# Build from current directory
a3s-box build -t my-app:v1 .

# With build args
a3s-box build -t my-app:v1 --build-arg VERSION=1.2.3 .

# Multi-platform
a3s-box build -t my-app:v1 --platform linux/amd64,linux/arm64 .

FROM alpine:latest
ADD https://example.com/config.tar.gz /etc/myapp/
COPY . /app
RUN echo "built"

FROM alpine:latest
ONBUILD COPY . /app
ONBUILD RUN cd /app && make

# Verify with cosign public key
a3s-box pull --verify-key cosign.pub ghcr.io/my-org/my-image:v1

# Keyless (OIDC) verification
a3s-box pull \
  --verify-issuer https://accounts.google.com \
  --verify-identity user@example.com \
  my-image:latest

# Bind mount
a3s-box run -v /host/data:/app/data my-image

# Named volume
a3s-box volume create my-data
a3s-box run -v my-data:/app/data my-image

# Copy files
a3s-box cp my-box:/app/output.txt ./output.txt
a3s-box cp ./config.json my-box:/app/config.json

# Default TSI — port mapping
a3s-box run -d --name web -p 8080:80 nginx:alpine

# Bridge network — inter-container communication
a3s-box network create my-net
a3s-box run -d --name db --network my-net postgres:15
a3s-box run -d --name app --network my-net my-app:latest
# app can reach db at "db:5432"

# Air-gapped
a3s-box run --network none alpine:latest

# Save box state
a3s-box snapshot create my-box checkpoint-1

# Restore
a3s-box snapshot restore my-box checkpoint-1

# List snapshots
a3s-box snapshot ls my-box

# compose.yaml
services:
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: secret
  app:
    image: my-app:latest
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8080:8080"

a3s-box compose up -d
a3s-box compose ps
a3s-box compose down

# Run with AMD SEV-SNP
a3s-box run -d --name secure --tee alpine:latest -- sleep 3600

# Simulation mode (no AMD hardware required)
a3s-box run -d --name dev --tee --tee-simulate alpine:latest -- sleep 3600

# Attest the VM
a3s-box attest secure --ratls

# Inject a secret over RA-TLS
a3s-box inject-secret secure --secret "API_KEY=my-secret" --set-env

# Seal data (only decryptable in same TEE context)
a3s-box seal secure --data "sensitive" --context myapp
a3s-box unseal secure --context myapp

# Detailed box info (JSON)
a3s-box inspect my-box

# Live resource usage
a3s-box stats

# Processes inside a box
a3s-box top my-box

# Filesystem changes
a3s-box diff my-box

# Stream events
a3s-box events --json

# Remove stopped boxes and unused images
a3s-box system-prune -f

# Unused images only
a3s-box image-prune

# Unused volumes
a3s-box volume prune