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

# Boot a fresh box

> A real Linux computer, on the internet, in under a second.

One command gives you a full Ubuntu 24.04 VM — Docker, Python, Go, agents, nginx, the usual tools — over SSH and at `https://name.boxd.sh`. Boots in \~30ms.

## How it works

`boxd machine new` boots a KVM microVM with a 100 GB disk and a proxy mapping `https://name.boxd.sh` → port 8000 (TLS, HTTP→HTTPS, WebSockets — handled). Real unminimized Ubuntu; you land as `boxd` with passwordless sudo.

## Use it

<Tabs>
  <Tab title="CLI">
    ```bash theme={"theme":"github-dark"}
    boxd machine new myapp
    ```

    ```text theme={"theme":"github-dark"}
        name: myapp
          id: 9645b1e8-193d-4d11-86b1-f91deff5bbfb
         url: myapp.boxd.sh
        boot: 30ms
    ```

    Add `--json` for a parseable response, useful in scripts:

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

    Then jump in:

    ```bash theme={"theme":"github-dark"}
    boxd connect myapp
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={"theme":"github-dark"}
    npm install @boxd-sh/sdk
    ```

    ```typescript theme={"theme":"github-dark"}
    import { Boxd } from "@boxd-sh/sdk";

    const boxd = new Boxd({ apiKey: "bxd_..." });

    const machine = await boxd.machines.create({ name: "myapp" });
    console.log(machine.access.url);   // https://myapp.boxd.sh
    console.log(machine.bootTimeMs);   // 30

    await boxd.machines.waitUntilReady(machine.id);
    const result = await boxd.machines.exec(machine.id, { command: ["echo", "hello"] });
    console.log(result.stdout);

    await boxd.close();
    ```

    Mint an API key with `boxd auth keys create NAME` or [in the console](https://boxd.sh/app). Full surface: [TypeScript SDK](/reference/typescript-sdk).
  </Tab>

  <Tab title="Python">
    ```bash theme={"theme":"github-dark"}
    pip install boxd
    ```

    ```python theme={"theme":"github-dark"}
    from boxd import Boxd

    with Boxd(api_key="bxd_...") as boxd:
        machine = boxd.machines.create("myapp")
        print(machine.access.url)        # https://myapp.boxd.sh
        print(machine.boot_time_ms)      # 30

        boxd.machines.wait_until_ready(machine.id)
        result = boxd.machines.exec(machine.id, "echo hello")
        print(result.stdout)
    ```

    Mint an API key with `boxd auth keys create NAME` or [in the console](https://boxd.sh/app). Full surface: [Python SDK](/reference/python-sdk).
  </Tab>
</Tabs>

`boxd machine new` auto-syncs the `myapp.boxd` alias into `~/.ssh/config`. Skip the name and boxd generates one like `blue-river`.

## What's already installed

Each box ships with a developer-ready Ubuntu 24.04:

* **Languages:** Python 3 (with `uv`, `pipx`), Go, `build-essential`, Node.js 24 via nvm
* **Agents:** Claude Code (`claude`), Codex (`codex`), pre-wired with `AGENTS.md` context
* **Containers:** Docker, Docker Compose, Buildx
* **Web:** nginx pre-installed on port 8000 (start it when you want it), headless Chrome
* **Tools:** `git`, `gh`, `jq`, `ripgrep`, `sqlite3`, `rsync`, `ffmpeg`, ImageMagick, `mitmproxy`
* **Editors:** vim, neovim, plus full SSH for Cursor/VS Code/Zed/JetBrains

Specs per VM: 2 vCPU, 8 GiB RAM, 100 GB disk. You can run up to 10 VMs (extendable on request).

## Custom images

Every box boots from `computer:latest`, a curated Ubuntu 24.04 image we maintain. The same image is kept warm across the fleet, which is how fresh boots stay around \~30ms.

Need something different? A different base distro, your own pre-installed toolchain, a specific CUDA stack, a slimmer surface area? Email [contact@boxd.sh](mailto:contact@boxd.sh) with what you want baked in. We package it and keep it warm across the fleet, so your boxes boot from your image with the same sub-second cold start as the default.

## Recipes

### Serve something instantly

```bash theme={"theme":"github-dark"}
boxd machine new hello
ssh hello.boxd 'python3 -m http.server 8000' &
open https://hello.boxd.sh
```

The default proxy forwards `name.boxd.sh` to port 8000. Any HTTP server on 8000 is live.

### Change the default port

```bash theme={"theme":"github-dark"}
boxd machine proxy set-port --vm myapp --port 3000
```

Use `--port=auto` to let boxd detect whichever port your app started listening on.

### Stop paying when idle

Boxes auto-hibernate after 4 hours of network idle by default — snapshot to disk, effectively free to keep, \~85ms wake on the next request. For tighter idle windows, enable auto-suspend: sub-millisecond resume.

```bash theme={"theme":"github-dark"}
boxd machine config set myapp auto-suspend.timeout 60     # suspend after 60s idle (off by default)
boxd machine config set myapp auto-hibernate.timeout 0    # never hibernate this box (default: 4h)
```

## FAQ

<AccordionGroup>
  <Accordion title="How is this different from a container?">
    Each box is a full KVM microVM with its own kernel, network stack, persistent disk, and public HTTPS domain. `systemd` runs as PID 1, Docker works without nesting tricks, and the filesystem survives reboots.
  </Accordion>

  <Accordion title="What happens to data when I reboot?">
    The 100 GB disk persists across reboots, suspends, and resumes. Only `boxd machine remove` removes it.
  </Accordion>

  <Accordion title="Where is the infrastructure?">
    EU-hosted on sovereign infrastructure.
  </Accordion>
</AccordionGroup>

## Next

<Columns cols={2}>
  <Card title="Fork from a golden" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/copy.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=f3623fe516eebf87b33b3a1022852286" href="/cloud-dev-boxes/fork-from-a-golden" width="16" height="16" data-path="images/icons/copy.svg">
    Skip the install step. Warm copies of your app in \~160ms.
  </Card>

  <Card title="Live demos & share URLs" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/global.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=c8aae834f6a656b39b1a152b1fd5242f" href="/cloud-dev-boxes/live-demos" width="16" height="16" data-path="images/icons/global.svg">
    Every box has a real HTTPS URL the moment a port is open.
  </Card>
</Columns>