Configuration
A3S Box state, environment variables, runtime options, and limits
Configuration
A3S Box configuration is currently mostly CLI-driven. There is no production HCL config file contract for the CLI path yet. The stable sources of configuration are command-line flags, persisted state under A3S_HOME, and a small set of environment variables.
State Layout
| Path | Purpose |
|---|---|
~/.a3s/boxes.json | Box records, names, status, image reference, ports, network, health, exit code. |
~/.a3s/images/ | Local OCI image cache. |
~/.a3s/volumes/ | Named volume data. |
~/.a3s/networks.json | User-defined network records and endpoints. |
~/.a3s/audit.jsonl | Persistent audit events. |
~/.a3s/boxes/<id>/ | Per-box rootfs, sockets, logs, and runtime files. |
Set A3S_HOME to isolate tests or run multiple environments:
A3S_HOME=/tmp/a3s-box-dev a3s-box ps -aEnvironment Variables
| Variable | Description |
|---|---|
A3S_HOME | Data directory. Default: ~/.a3s. |
A3S_IMAGE_CACHE_SIZE | Image cache size. Default: 10g. |
A3S_TEE_SIMULATE | Enables simulated TEE behavior. |
A3S_REGISTRY_PROTOCOL | Registry protocol override, mainly for local/insecure registry tests. |
A3S_BOX_CRI_AGENT_IMAGE | Default CRI sandbox agent/rootfs image. |
A3S_BOX_UNSAFE_HOST_RUN | Opt into unsafe macOS host execution for Dockerfile RUN experiments. |
RUST_LOG | Tracing log level. |
Smoke-test variables are documented in the repository README and test files: A3S_BOX_SMOKE_IMAGE, A3S_BOX_SMOKE_IMAGE_TAR, A3S_BOX_SMOKE_SKIP_PULL, A3S_BOX_SMOKE_TIMEOUT_SECS, and A3S_BOX_TEST_ALPINE_TAR.
Runtime Resources
a3s-box run --cpus 4 --memory 2g alpine:latest -- sleep 3600Boot-time CPU and memory are configured before the MicroVM starts. Running VMs cannot have vCPU or memory size changed because libkrun does not expose that hot-resize API. container-update validates this boundary and can update supported lifecycle/restart metadata and guest-level limits where applicable.
Supported resource limit flags include:
--pids-limit;--cpuset-cpus;--ulimit name=soft:hard;--cpu-shares,--cpu-quota,--cpu-period;--memory-reservation,--memory-swap.
Linux cgroup v2 controls are best-effort and depend on host permissions/delegation.
Process Configuration
A3S Box merges image metadata and CLI overrides in this order:
- image
ENTRYPOINT,CMD,ENV,WORKDIR,USER,STOPSIGNAL, andHEALTHCHECK; - env files;
- inline
--envvalues; - CLI overrides such as
--entrypoint,CMD...,--workdir,--user,--stop-signal, and health flags.
Validation is intentionally early. Unsupported named users, relative workdirs, invalid hostnames, invalid --add-host entries, and unsupported security options fail before the VM is booted or persistent state is written.
Logging
a3s-box run --log-driver json-file --log-opt max-size=100m alpine:latest -- echo ok
a3s-box logs --tail 100 box-name
a3s-box logs -f box-namejson-file is the default. none disables box log capture.
Health and Restart
a3s-box run -d --name api \
--health-cmd 'curl -f http://localhost/health || exit 1' \
--health-interval 30 \
--health-timeout 5 \
--health-retries 3 \
--restart on-failure:3 \
myapi:latestThe monitor command performs restart-policy recovery for detached boxes. Health checks and restart behavior are covered by unit and real-runtime smoke tests, but they still depend on the guest image containing the health command you specify.