Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt

Use this file to discover all available pages before exploring further.

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.
--imagecomputer:latestContainer image for the root filesystem.
--restartalwaysRestart policy: always or never.
If you omit --name, boxd generates a random name like blue-river. Output: 
creating myapp...
name: myapp
  id: 9645b1e8-193d-4d11-86b1-f91deff5bbfb
 url: myapp.boxd.sh
boot: 1.3s
Connect via SSH: ssh myapp.boxd.sh

Or from your browser: https://myapp.boxd.sh
With --json: 
{
  "name": "myapp",
  "vm_id": "9645b1e8-193d-4d11-86b1-f91deff5bbfb",
  "url": "myapp.boxd.sh",
  "image": "default",
  "status": "running",
  "boot_time_ms": 1300
}

​
List

ssh boxd.sh list

name    status   url                image
myapp   running  myapp.boxd.sh      default
test    running  test.boxd.sh       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 pip, 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 24 is installed via nvm and available in interactive shells (SSH, boxd connect). It is not on PATH for non-interactive boxd exec calls, which use /bin/sh -c and don’t source ~/.bashrc. To use Node from boxd exec, either source nvm first (. ~/.nvm/nvm.sh && node ...) or install it system-wide (sudo apt install -y nodejs npm).
The boxd user has passwordless sudo and is a member of the docker group.