Skip to main content

​
State directory

BoxRun stores all state in a single directory: 
~/.boxrun/
├── boxrun          # BoxRun binary (installed by install script)
├── boxrun.db       # SQLite (boxes, execs, event log)
└── runtime/        # BoxLite runtime (kernel, shim, libraries)
No etcd, no Redis, no container runtime, no image registry.

​
Environment variables

VariableDefaultDescription
BOXRUN_STATE_DIR~/.boxrunState directory (socket, database)
BOXRUN_SOCKET~/.boxrun/boxrun.sockUnix socket path
BOXRUN_DB~/.boxrun/boxrun.dbSQLite database path
BOXRUN_HOST127.0.0.1Server bind host (TCP mode)
BOXRUN_PORT9090Server bind port (TCP mode)
BOXRUN_MAX_CPUauto-detectedTotal CPU limit override
BOXRUN_MAX_MEMORY_MBauto-detectedTotal memory limit override (MB)
BOXLITE_RUNTIME_DIR./runtimeBoxLite runtime directory

​
Resource limits

Total CPU and memory limits are auto-detected from host hardware. There is no hard limit on box count — you can run as many boxes as your CPU and memory allow.

​
Defaults

ResourceDefault
Total CPUauto-detected (host CPU count)
Total memoryauto-detected (host RAM)
Per-box CPU2 cores
Per-box memory1024 MB
Per-box disk8 GB
Per-box workdir/root
Default imageubuntu:24.04

​
Overriding limits

Override total resource limits via environment variables: 
export BOXRUN_MAX_CPU=8
export BOXRUN_MAX_MEMORY_MB=8192
Configure per-box resources at creation time: 
boxrun create ubuntu:24.04 --name beefy --cpu 4 --memory 2048

​
Image aliases

BoxRun resolves short image names to full references:
AliasImage
ubuntuubuntu:24.04
pythonpython:3.12-slim
nodenode:22-slim
golanggolang:1.22
rustrust:1.77-slim
alpinealpine:3.20
You can also use any valid OCI image reference directly (e.g. python:3.11, nginx:latest).

​
Checking current limits

curl http://localhost:9090/v1/info
# {"max_cpu": 8, "max_memory_mb": 16384}