BoxRun provides a single boxrun command with subcommands for managing boxes, executing commands, transferring files, and more.
BOX arguments accept either a box ID (box_abc123) or a name (dev).
Server
boxrun serve [--host 127.0.0.1] [--port 9090] [--socket PATH]
127.0.0.1:9090. Use --socket to bind to a Unix domain socket instead.
The web dashboard is available at http://<host>:<port>/ui when running in TCP mode.
The server starts automatically on your first command — you rarely need to run this manually.
Box lifecycle
Create
boxrun create [IMAGE] [--name NAME] [--cpu 2] [--memory 1024] [--disk 8] [--network] [-v /host:/guest[:ro]]
IMAGE is omitted, defaults to ubuntu:24.04.
| Flag | Default | Description |
|---|
--name, -n | (auto) | Human-readable name |
--cpu | 2 | CPU cores |
--memory, -m | 1024 | Memory in MB |
--disk | 8 | Disk size in GB |
--network | false | Enable networking |
-v, --volume | (none) | Volume mount (repeatable) |
List
boxrun ls [--status running|stopped|all]
Stop
Stop a running box. Disk state is preserved — restart it later with boxrun start.
Start
Restart a previously stopped box with its disk intact.
Remove
Remove a box permanently. Use --force to remove a running box without stopping it first.
Interactive terminal
boxrun attach BOX [--shell /bin/bash]
- Full PTY support — vim, htop, tmux all work
- Automatic terminal resize handling
- Raw terminal mode — same experience as SSH
- The box keeps running if you disconnect — reattach anytime
Exit with Ctrl-D or type exit.
Shell shortcut
boxrun shell IMAGE [--name NAME] [--cpu 2] [--memory 1024] [--disk 8] [--shell /bin/bash] [-v /host:/guest[:ro]]
create + attach in one command. Accepts the same resource flags as create.
boxrun shell ubuntu
boxrun shell python --name pydev --memory 2048
Command execution
boxrun exec BOX -- CMD [ARGS...]
| Flag | Description |
|---|
--detach, -d | Return the exec ID immediately without waiting |
--timeout, -t | Timeout in seconds |
# Run a command
boxrun exec dev -- uname -a
# With timeout
boxrun exec dev --timeout 30 -- python3 train.py
# Detached (background)
boxrun exec dev --detach -- long-running-job.sh
File transfer
boxrun cp LOCAL_PATH BOX:REMOTE_PATH # upload
boxrun cp BOX:REMOTE_PATH LOCAL_PATH # download
BOX:PATH syntax.
# Upload a file
boxrun cp ./data.csv dev:/root/data.csv
# Download results
boxrun cp dev:/root/results.csv ./results.csv
Ephemeral run
boxrun run IMAGE -- CMD [ARGS...] [--timeout SECONDS] [--disk 8]
boxrun run ubuntu -- echo "hello"
boxrun run python --timeout 30 -- python3 -c "print(42)"
Volume mounts
Share host directories into VMs using Docker-style -v syntax:
# Read-write mount
boxrun create ubuntu:24.04 --name dev -v ~/project:/root/project
# Read-only mount
boxrun create ubuntu:24.04 --name dev -v ~/data:/mnt/data:ro
# Multiple mounts
boxrun create ubuntu:24.04 -v /src:/root/src -v /data:/mnt/data:ro
Garbage collection
boxrun gc [--older-than 3600]
--older-than seconds (default: 1 hour).
Images
List available images with their aliases.
Image aliases
BoxRun provides built-in aliases for common images so you can use short names:
| Alias | Image | Description |
|---|
default | ubuntu:24.04 | General purpose (used when no image is specified) |
ubuntu | ubuntu:24.04 | Ubuntu 24.04 LTS |
python | python:3.12-slim | Python 3.12 pre-installed |
node | node:22-slim | Node.js 22 LTS pre-installed |
golang | golang:1.22 | Go 1.22 pre-installed |
rust | rust:1.77-slim | Rust 1.77 pre-installed |
alpine | alpine:3.20 | Lightweight Linux (5 MB) |
# These are equivalent
boxrun shell ubuntu
boxrun shell ubuntu:24.04
# Use aliases anywhere an image is accepted
boxrun create python --name pydev
boxrun run node -- node -e "console.log('hello')"
boxrun images to see all available aliases.
Shell completions
# Zsh (add to ~/.zshrc)
eval "$(boxrun completion zsh)"
# Bash (add to ~/.bashrc)
eval "$(boxrun completion bash)"
# Fish
boxrun completion fish | source
