Quickstart

Boxd machines are lightning fast, persistent, hardware-isolated linux environments for developers, agents, apps, and automations. We’ve optimized our machines to make you develop faster. The recommended way to use boxd is through our CLI. However, for use cases that require orchestration and automation, we’d recommend our TypeScript and Python SDKs. To get started, we recommend you go through the onboarding on app.boxd.sh. If you prefer the terminal, below are the steps to get you going quickly.

1. Install

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

This script auto-detects your platform, verifies checksums, and installs the latest boxd CLI to ~/.local/bin/boxd.

2. Authenticate

CLI
TypeScript
Python

boxd auth login

Add the SDK and mint a key:

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

Add the SDK and mint a key:

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

boxd new boots a fresh machine in milliseconds.

3. Create a machine

CLI
TypeScript
Python

boxd new myapp

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

const boxd = new Boxd();                              // reads BOXD_API_KEY
const machine = await boxd.machines.create({ name: "myapp" });
console.log(machine.access.url, machine.bootTimeMs);

from boxd import Boxd

boxd = Boxd()                              # reads BOXD_API_KEY
machine = boxd.machines.create("myapp")
print(machine.access.url, machine.boot_time_ms)

You’ll see:

    name: myapp
      id: 9645b1e8-193d-4d11-86b1-f91deff5bbfb
     url: myapp.boxd.sh
     source: standalone
    boot: 30ms

Connect via SSH: ssh myapp.boxd
Or from your browser: https://myapp.boxd.sh

You’ve created your first machine. Great work. This 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.

4. Get into the machine

boxd connect myapp

You get a shell on the machine straight away. Type exit or Ctrl-D to come back to your local shell.

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

ssh myapp.boxd

You get a normal shell on the machine, as the boxd user with passwordless sudo. It is real SSH, so scp, rsync, ssh -L and your editor’s Remote-SSH all work too.

5. Serve something on your public URL

Every machine already has a public HTTPS address at https://myapp.boxd.sh. Anything you run on port 8000 is served there. To see it working, start the nginx that comes pre-installed:

CLI
TypeScript
Python

boxd machine exec myapp -- sudo systemctl start nginx

await boxd.machines.exec(machine.id, { command: ["sudo", "systemctl", "start", "nginx"] });

boxd.machines.exec(machine.id, "sudo systemctl start nginx")

Now open https://myapp.boxd.sh in your browser. You are looking at a server running on your machine, reachable by anyone you send the link to. Swap nginx for your own app on port 8000 and the same URL serves that instead.

6. Fork your machine

A fork is a copy of a machine exactly as it is right now, including its disk, its memory, and whatever it is running. Fork the machine you just set up:

CLI
TypeScript
Python

boxd machine fork myapp myapp-test

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

fork = boxd.machines.fork("myapp", "myapp-test")
print(fork.access.url)   # https://myapp-test.boxd.sh

That takes milliseconds. You now have a second machine, myapp-test, with its own URL at https://myapp-test.boxd.sh. The important part is that running processes come with it. The nginx you started in step 5 is already serving on the fork’s URL. Nothing had to boot or start up again. Open both URLs side by side and you will see the same page twice.

7. Snapshot your machine

A snapshot is a saved copy of a machine that you keep. A fork gives you a second machine running right now. A snapshot gives you an image you can create machines from later, and it stays around even after you delete the machine it came from. Save myapp as a snapshot:

CLI
TypeScript
Python

boxd snapshots save myapp my-workspace

await boxd.snapshots.create(machine.id, "my-workspace");

boxd.snapshots.create(machine.id, "my-workspace")

The machine keeps running while it saves. Now you can stamp out fresh machines from that saved state whenever you want:

CLI
TypeScript
Python

boxd machine new fresh --from-snapshot my-workspace

await boxd.machines.create({ fromSnapshot: "my-workspace", name: "fresh" });

boxd.machines.create("fresh", from_snapshot="my-workspace")

Each one comes up in the saved state, so this is how you keep a known-good setup and hand copies of it to your team or to an agent.

8. Make a checkpoint

A checkpoint is an undo button for one machine. Save one before you try something risky, and if it goes wrong, rewind the same machine back to that moment. The machine keeps its name and its URL. Save a checkpoint:

CLI
TypeScript
Python

boxd machine checkpoint save myapp before-changes

await boxd.machines.checkpoints.create(machine.id, "before-changes");

boxd.machines.checkpoints.create(machine.id, "before-changes")

Then if a change goes wrong, roll the machine back:

CLI
TypeScript
Python

boxd machine checkpoint restore myapp before-changes -y

await boxd.machines.checkpoints.restore(machine.id, "before-changes");

boxd.machines.checkpoints.restore(machine.id, "before-changes")

The machine reboots into exactly the state it was in when you saved. Checkpoints live on the machine, so they go away when you delete it. Use a snapshot when you want something that outlives the machine.

9. Talk between machines

Machines can manage each other. The boxd CLI and both SDKs are already installed on every machine, and inside a machine they sign in as you automatically. There is no API key to copy in and nothing to configure. Get into myapp as you did in step 4, then run any of these from in there:

CLI
TypeScript
Python

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

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

const boxd = new Boxd();          // no API key needed in here
for (const m of await boxd.machines.list()) {
  console.log(m.name, m.status);
}

from boxd import Boxd

boxd = Boxd()                     # no API key needed in here
for machine in boxd.machines.list():
    print(machine.name, machine.status)

To control which machines are allowed to reach which, see VM to VM. Machines are private to you by default. Sharing one opens it to every member of your org, so a teammate can connect to it and work in the same machine.

CLI
TypeScript
Python

boxd machine share myapp     # every member of your org can now reach it
boxd machine unshare myapp   # private to you again

await boxd.machines.share(machine.id);
await boxd.machines.unshare(machine.id);

boxd.machines.share(machine.id)
boxd.machines.unshare(machine.id)

Only the owner can share or unshare a machine, and sharing never moves it between organizations. It only changes who can reach it.

Sharing wipes the agent logins inside the machine, so a teammate with a shell can never read your Claude Code, Codex, or OpenCode tokens. Do not share a machine an agent is working in, because it gets logged out immediately. If you want a copy with your logins intact, fork the machine instead. A fork of a shared machine is private to you.

See VM sharing for more information.

What’s next

Dive deeper into the guides, or explore the use cases.

Development workspaces

A real computer for you and your team.

Preview environments

A URL for every pull request.

Coding agents

Give an agent its own machine to work in.

Personal assistants

An always-on machine your assistant lives on.

Sandboxes

Run untrusted code behind a hardware boundary.

Agentic SaaS offerings

Give every one of your users their own machine.

Getting started

Guides

Use cases

References

1. Install

2. Authenticate

3. Create a machine

4. Get into the machine

5. Serve something on your public URL

6. Fork your machine

7. Snapshot your machine

8. Make a checkpoint

9. Talk between machines

What’s next

Development workspaces

Preview environments

Coding agents

Personal assistants

Sandboxes

Agentic SaaS offerings

​1. Install

​2. Authenticate

​3. Create a machine

​4. Get into the machine

​5. Serve something on your public URL

​6. Fork your machine

​7. Snapshot your machine

​8. Make a checkpoint

​9. Talk between machines

​10. Share a machine

​What’s next

Development workspaces

Preview environments

Coding agents

Personal assistants

Sandboxes

Agentic SaaS offerings

1. Install

2. Authenticate

3. Create a machine

4. Get into the machine

5. Serve something on your public URL

6. Fork your machine

7. Snapshot your machine

8. Make a checkpoint

9. Talk between machines

10. Share a machine

What’s next