Quickstart - boxd

If you’re an AI agent reading this, fetch llms.txt or llms-full.txt instead. They’re built for you.

1. Install

One command, before anything else:

curl -fsSL https://boxd.sh/downloads/install.sh | sh

Gets you the boxd CLI and the <vm>.boxd SSH aliases. The client utilities (clipboard, files, and browser into every VM) are built in too — turn them on with boxd client enable. Then pick your client:

SSH
CLI
TypeScript
Python

Nothing to install — your SSH key is already linked. Drive the control plane straight from your terminal:

ssh boxd.sh

boxd login

Add the SDK and mint a key:

npm install @boxd-sh/sdk
export BOXD_API_KEY=$(boxd keys create my-app)

Add the SDK and mint a key:

pip install boxd
export BOXD_API_KEY=$(boxd keys create my-app)

2. Create a machine

SSH
CLI
TypeScript
Python

ssh boxd.sh new --name=myapp

Running a bunch of commands in a row? Drop into the REPL with just ssh boxd.sh (no args) and run them without the prefix:

$ ssh boxd.sh
boxd> new --name=myapp
boxd> fork myapp --name=myapp-test
boxd> list
boxd> exit

boxd new --name=myapp

import { Compute } from "@boxd-sh/sdk";

const c = new Compute();                              // reads BOXD_API_KEY
const box = await c.box.create({ name: "myapp" });
console.log(box.url, box.bootTimeMs);

from boxd import Compute

c = Compute()                              # reads BOXD_API_KEY
box = c.box.create(name="myapp")
print(box.url, box.boot_time_ms)

You’ll see:

    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

The machine has a persistent disk and its own HTTPS domain. TLS is already terminated. Visit the URL. You’ll see a default landing page until you start a server.

From the SDKs, give the VM a couple of seconds before the first exec. create and fork return as soon as the VM is scheduled; the in-VM exec endpoint takes another second or two to accept connections. The SSH and CLI paths handle the wait for you.

3. Get into the box

The install in step 1 wrote the myapp.boxd alias into your SSH config. SSH straight to the machine by name:

ssh myapp.boxd

A real shell as boxd (passwordless sudo) — plus scp, rsync, ssh -L, and editor Remote-SSH.

Command	What it is
`ssh myapp.boxd`	the machine — a shell inside your VM
`ssh boxd.sh`	the control plane — create / list / fork / destroy

Drove the control plane over plain SSH instead?

No SSH config, no alias — shell in through the control plane:

ssh -t boxd.sh connect myapp

From code, drive the box with exec rather than shelling in.

boxd connect myapp

Drops you straight into an interactive shell on the machine over the boxd API — no SSH config, no host keys. Auto-resumes paused or hibernated machines. Type exit or Ctrl-D to come back to your local shell.

4. Make it live

nginx is pre-installed on port 8000 (the default proxy port). Start it:

SSH
CLI
TypeScript
Python

ssh boxd.sh exec myapp -- sudo systemctl start nginx

Already in the boxd> REPL? Just:

exec myapp -- sudo systemctl start nginx

boxd exec myapp -- sudo systemctl start nginx

await box.exec(["sudo", "systemctl", "start", "nginx"]);

box.exec("sudo", "systemctl", "start", "nginx")

Refresh https://myapp.boxd.sh. Your machine is live on the internet.

5. Forking

SSH
CLI
TypeScript
Python

ssh boxd.sh fork myapp --name=myapp-test

Already in the boxd> REPL? Just:

fork myapp --name=myapp-test

boxd fork myapp --name=myapp-test

const fork = await c.box.fork("myapp", { name: "myapp-test" });
console.log(fork.url);   // myapp-test.boxd.sh

fork = c.box.fork("myapp", name="myapp-test")
print(fork.url)   # myapp-test.boxd.sh

~160ms for a full disk copy. The fork has its own HTTPS domain and a complete snapshot of myapp at the moment of the fork. Running processes come with it. If myapp had a Python server listening on port 8000, the fork is already serving on https://myapp-test.boxd.sh the instant it boots. Run experiments on myapp-test; the original is untouched. Get into the fork the same way: ssh myapp-test.boxd.

6. Talk between VMs

Every boxd VM ships the same boxd CLI inside. From within either machine you can see, exec into, and copy files between any of your own VMs. No keys, no tokens — auth is automatic by source IP.

ssh myapp.boxd
# inside myapp:
boxd list                                  # see myapp and myapp-test
boxd exec myapp-test 'hostname'            # run a command on the fork
boxd cp ./file myapp-test:/tmp/file        # copy something across

The in-VM path is what makes fleets of agents practical — an agent on one VM spawning, exec’ing into, and tearing down siblings without a credential to manage. Full mechanics: VM-to-VM networking. When you’re done with the fork:

SSH
CLI
TypeScript
Python

ssh boxd.sh destroy myapp-test -y

boxd destroy myapp-test -y

await fork.destroy();

fork.destroy()

What’s next

Boot a fresh box

All the ways to spin up a VM and configure it.

Fork from a golden

Pre-warm an app, fork it on demand, destroy when done.

Per-PR preview URLs

A boxd URL on every pull request.

Agent sandboxes

Give your agent its own real computer.

​1. Install

​2. Create a machine

​3. Get into the box

​4. Make it live

​5. Forking

​6. Talk between VMs

​What’s next

Boot a fresh box

Fork from a golden

Per-PR preview URLs

Agent sandboxes

1. Install

2. Create a machine

3. Get into the box

4. Make it live

5. Forking

6. Talk between VMs

What’s next