Skip to main content
A machine is a KVM microVM with its own kernel, network stack, persistent disk, public IP, and HTTPS domain.

​
Create

ssh boxd.sh new --name=myapp
FlagDefaultDescription
--nameauto-generatedMachine name. Must be unique across the cluster. Becomes the subdomain.
--imagecluster defaultContainer image for the root filesystem.
--restartalwaysRestart policy: always or never.
If you omit --name, boxd generates a random name like blue-river. Output: 
   name: myapp
     id: 9645b1e8-193d-4d11-86b1-f91deff5bbfb
     ip: 5.135.42.17
   boot: 1.8s
With --json: 
{
  "name": "myapp",
  "vm_id": "9645b1e8-193d-4d11-86b1-f91deff5bbfb",
  "ip": "5.135.42.17",
  "image": "default",
  "status": "running",
  "boot_time_secs": 1.8
}

​
List

ssh boxd.sh list

name    status   ip          image
myapp   running  5.135.42.17 default
test    running  5.135.42.18 default
Returns no VMs if you have none.

​
Destroy

ssh boxd.sh destroy myapp

destroyed myapp
The name and IP are reserved — recreating a machine with the same name reuses the same IP when possible.

​
What’s inside

The default image is Ubuntu 24.04 (unminimized, with man pages and full documentation): Languages and runtimes:
  • Python 3 with uv package manager and pipx
  • Go (golang-go)
  • build-essential (gcc, g++, make)
Coding agents:
  • Claude Code (claude) — Anthropic’s CLI coding agent
  • Codex (codex) — OpenAI’s CLI coding agent
Use them with a subscription (e.g., Claude Max) or by setting an API key inside your machine. Each machine includes an AGENTS.md at ~/.config/boxd/AGENTS.md that gives agents context about the boxd environment. It’s symlinked to ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md automatically. Containers:
  • Docker and Docker Compose
  • Docker Buildx
Editors:
  • vim, neovim
Tools:
  • git, curl, wget, jq, ripgrep, sqlite3, rsync, tree, file, unzip
  • GitHub CLI (gh)
Monitoring:
  • btop, atop, iotop, ncdu
Media:
  • ffmpeg, ImageMagick
Network:
  • mitmproxy, socat, netcat
  • Headless Chrome (via headless-shell)
System:
  • nginx (configured on port 8000, disabled by default)
  • systemd (full init system)
  • openssh-server, openssh-client
Node.js is not pre-installed. Install it with sudo apt install -y nodejs npm or use a version manager like nvm.
The boxd user has passwordless sudo and is a member of the docker group.