Managing machines

@boxd/run re-exports the boxd TypeScript SDK as boxd, already authenticated for the machine it runs on. Import it and call it.

import { boxd } from "@boxd/run";

const machines = await boxd.machines.list();

Everything the SDK offers is there: machines, snapshots, checkpoints, disks, env vars and secrets, domains, organizations, API keys. This page covers what is specific to using it from an automation. The method reference is the SDK page.

What it can reach

The client is scoped like the machine it runs on:

Where the script runs	What `boxd` can manage
A private machine	Your machines in that organization
A shared machine	The organization’s shared machines only, never a member’s private ones
An isolated machine	None. Isolated machines have no `run` and no SDK credential

The in-machine boxd CLI follows the same rule. On a private machine the script acts as the machine’s owner, fenced to that organization. On a shared machine it acts for the org’s shared machines only.

Fan work out to fresh machines

The reason to reach for the SDK from an automation is usually fan-out. Something happens, and you want one clean machine per unit of work instead of doing it all on the machine the script lives on.

review-on-pr.run.ts

import { boxd, githubApp } from "@boxd/run";

githubApp.on("pull_request.opened", { repo: "acme/api" }, async (pr) => {
  const machine = await boxd.machines.create({ fromSnapshot: "api-main", name: `review-${pr.number}` });
  try {
    await boxd.machines.waitUntilReady(machine.id);
    const r = await boxd.machines.exec(machine.id, {
      command: ["sh", "-c", `git fetch origin pull/${pr.number}/head && git checkout FETCH_HEAD && claude -p 'Review the diff against main and print findings'`],
      timeout: 15 * 60_000,
    });
    const gh = await githubApp.client();
    await gh.rest.issues.createComment({ owner: "acme", repo: "api", issue_number: pr.number, body: r.stdout });
  } finally {
    await boxd.machines.delete(machine.id);
  }
});

machines.create({ fromSnapshot }) creates a machine from a snapshot with everything already installed and running, except the snapshot’s automations, which start paused (see below). exec collects stdout, stderr, exitCode and success. An array command is shell-quoted for you, and a string is passed to a shell as is.

Fork the machine you are on

A fork copies a running machine, memory and disk included, in under 200ms. From a script that means “take a copy of exactly this state and try something on it”:

import { boxd } from "@boxd/run";

const me = process.env.BOXD_VM_NAME!;
const fork = await boxd.machines.fork(me, { name: `${me}-experiment` });
await boxd.machines.waitUntilReady(fork.id);
const r = await boxd.machines.exec(fork.id, { command: ["sh", "-c", "npm test"] });
console.log(r.success ? "green on the fork" : r.stderr);
await boxd.machines.delete(fork.id);

A forked machine also inherits the automations of its source machine, paused, so nothing runs twice; the same goes for a machine created from a snapshot. fork.pausedAutomations says how many. To scale an automation out, start it on each copy with run restart <id>, for example through exec. See Jobs.

Checkpoint before a risky step

const me = process.env.BOXD_VM_NAME!;
await boxd.machines.checkpoints.create(me, "before-migration");
try {
  await riskyMigration();
} catch (e) {
  await boxd.machines.checkpoints.restore(me, "before-migration");   // back to the moment before
  throw e;
}

Checkpoints are per-machine save points, up to ten per machine.

Clean up a fleet on a schedule

import { boxd, every } from "@boxd/run";

every("1 hour", async () => {
  const stale = (await boxd.machines.list()).filter(
    (m) => m.name.startsWith("review-") && m.createdAt && Date.now() - m.createdAt.getTime() > 6 * 3600_000,
  );
  for (const m of stale) await boxd.machines.delete(m.id);
});

Your laptop, through the same object

boxd.local is the laptop bridge: files under your home directory and a Chrome on your laptop, through the client utilities. It is covered in Scripts and Browsers.

Errors

SDK calls throw typed errors exactly as on the SDK page. A script that lets one escape a handler logs it and carries on. One that lets it escape the top level counts as a crash and enters the retry ladder.

Getting started

Guides

Integrations and automations

Use cases

References

Managing machines

What it can reach

Fan work out to fresh machines

Fork the machine you are on

Checkpoint before a risky step

Clean up a fleet on a schedule

Your laptop, through the same object

Errors

​What it can reach

​Fan work out to fresh machines

​Fork the machine you are on

​Checkpoint before a risky step

​Clean up a fleet on a schedule

​Your laptop, through the same object

​Errors

What it can reach

Fan work out to fresh machines

Fork the machine you are on

Checkpoint before a risky step

Clean up a fleet on a schedule

Your laptop, through the same object

Errors