> ## 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.

# The VM model

> Each boxd VM is a full Linux microVM with its own kernel, disk, and HTTPS domain.

A machine is a KVM microVM with its own kernel, network stack, persistent disk, and public HTTPS domain. It's reachable on the internet through the proxy: HTTPS by domain, SSH on a dedicated per-VM port.

## Create

```bash theme={"theme":"github-dark"}
boxd machine new myapp
```

| Argument / Flag            | Default        | Description                                            |
| -------------------------- | -------------- | ------------------------------------------------------ |
| `NAME` (positional)        | auto-generated | Machine name. Must be unique. Becomes the subdomain.   |
| `--auto-suspend-timeout`   | server default | Idle seconds before auto-suspend. `0` disables.        |
| `--auto-hibernate-timeout` | server default | Idle seconds before cold auto-hibernate. `0` disables. |

If you omit the 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: 30ms
Connect via SSH: ssh myapp.boxd

Or from your browser: https://myapp.boxd.sh
```

With `--json`:

```json theme={"theme":"github-dark"}
{
  "name": "myapp",
  "vm_id": "9645b1e8-193d-4d11-86b1-f91deff5bbfb",
  "url": "myapp.boxd.sh",
  "image": "default",
  "status": "running",
  "boot_time_ms": 30
}
```

## List

```bash theme={"theme":"github-dark"}
boxd machine 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

```bash theme={"theme":"github-dark"}
boxd machine remove myapp -y
```

```
destroyed myapp
```

The name (and its proxy + SSH port) are reserved -- recreating a machine with the same name reuses them 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

<Note color="#E05A6D">
  Node.js 24 is installed via nvm and available in **interactive shells** (SSH, `boxd connect`). It is not on PATH for non-interactive `boxd machine exec` calls, which use `/bin/sh -c` and don't source `~/.bashrc`. To use Node from `boxd machine exec`, either source nvm first (`. ~/.nvm/nvm.sh && node ...`) or install it system-wide (`sudo apt install -y nodejs npm`).
</Note>

The `boxd` user has passwordless sudo and is a member of the `docker` group.