Agent swarm intelligence

A swarm splits a problem across many worker agents and merges their findings into one answer. On boxd, each worker gets a full machine of its own, with Claude Code, Codex, and OpenCode already installed and logged in, so a worker is one exec away from doing real work. Machines boot in about 30ms and cost near zero when idle, which makes spawning a machine per worker feel like calling a function.

Three scouts research in parallel, one machine each, then a lead agent reads all three reports and writes the recommendation.

How it works

The coordinator (your script, or an agent on a boxd machine) defines the sub-tasks.
It creates one machine per worker, fresh or forked from a warm baseline.
Each worker runs a coding agent headless inside its machine, and the output comes back through exec.
A lead step reads every report and writes the synthesis.
Workers are destroyed, and the fleet goes back to zero.

Full example

Three scouts research the same question through different lenses, then a lead agent reads all three reports and produces one recommendation:

Python
TypeScript

from concurrent.futures import ThreadPoolExecutor
from boxd import Boxd

LENSES = {
    "market": "Size the market for on-device speech models. Write a compact report.",
    "tech":   "Survey the strongest open-source on-device speech models. Write a compact report.",
    "risks":  "List the main risks of betting on on-device speech models. Write a compact report.",
}

boxd = Boxd()   # reads BOXD_API_KEY; authenticates automatically inside a VM

def scout(name: str, prompt: str) -> str:
    machine = boxd.machines.create(name)
    boxd.machines.wait_until_ready(machine.id)
    result = boxd.machines.exec(
        machine.id,
        f'claude -p "{prompt}" --dangerously-skip-permissions',
        timeout=600,
    )
    boxd.machines.delete(machine.id)
    return result.stdout

with ThreadPoolExecutor() as pool:
    reports = list(pool.map(
        lambda kv: scout(f"scout-{kv[0]}", kv[1]), LENSES.items()
    ))

# Lead agent: one more machine reads every report and merges them
lead = boxd.machines.create("lead")
boxd.machines.wait_until_ready(lead.id)
boxd.machines.files.upload(lead.id, "/home/boxd/reports.md", "\n\n---\n\n".join(reports))
final = boxd.machines.exec(
    lead.id,
    'claude -p "Read /home/boxd/reports.md and write one recommendation." '
    "--dangerously-skip-permissions",
    timeout=600,
)
print(final.stdout)
boxd.machines.delete(lead.id)

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

const LENSES: Record<string, string> = {
  market: "Size the market for on-device speech models. Write a compact report.",
  tech:   "Survey the strongest open-source on-device speech models. Write a compact report.",
  risks:  "List the main risks of betting on on-device speech models. Write a compact report.",
};

const boxd = new Boxd();   // reads BOXD_API_KEY; authenticates automatically inside a VM

async function scout(name: string, prompt: string): Promise<string> {
  const machine = await boxd.machines.create({ name });
  await boxd.machines.waitUntilReady(machine.id);
  const result = await boxd.machines.exec(machine.id, {
    command: `claude -p "${prompt}" --dangerously-skip-permissions`,
    timeout: 600_000,
  });
  await boxd.machines.delete(machine.id);
  return result.stdout;
}

const reports = await Promise.all(
  Object.entries(LENSES).map(([lens, prompt]) => scout(`scout-${lens}`, prompt))
);

// Lead agent: one more machine reads every report and merges them
const lead = await boxd.machines.create({ name: "lead" });
await boxd.machines.waitUntilReady(lead.id);
await boxd.machines.files.upload(lead.id, "/home/boxd/reports.md", reports.join("\n\n---\n\n"));
const final = await boxd.machines.exec(lead.id, {
  command: `claude -p "Read /home/boxd/reports.md and write one recommendation." --dangerously-skip-permissions`,
  timeout: 600_000,
});
console.log(final.stdout);
await boxd.machines.delete(lead.id);
await boxd.close();

The workers need nothing installed first, because the agents ship in the image and Claude Code is already logged in on every machine you own. See Coding agents.

Stage	What happens
Fan out	The coordinator creates one machine per lens
Work	A coding agent runs headless inside each worker
Collect	Each report comes back as the `exec` result
Synthesize	A lead machine reads all reports and writes one answer
Teardown	Workers are destroyed, and the fleet is gone

Workers can do more than report back at the end. Inside any of your machines, <vmname>.boxd resolves to that machine’s private IP, so a swarm can share a queue, a database, or a scoreboard by running it on one machine and letting the others connect by name:

curl http://coordinator.boxd:8000/next-task
psql -h shared-db.boxd -U postgres

Name resolution is private to your account, and only machines you own resolve. See VM to VM.

Let the swarm run itself

The coordinator can be a machine too. Every boxd VM carries the in-VM boxd CLI and the SDKs, pre-authenticated as your account, so an agent inside one machine can spawn siblings, hand them work, and clean up. The example above runs unchanged on a boxd machine, where Boxd() needs neither a key nor configuration.

Production tips

Warm-start workers with a fork

A fresh machine is generic, and a worker that needs your repo, dependencies, or a loaded model should start from a prepared baseline instead. Set the baseline up once, then boxd.machines.fork("baseline", name) per worker. Each fork lands in about 160ms with the baseline’s disk and memory intact. For a baseline that outlives the machine and stays versioned, use a golden image, and for identical starting states at scale see Reproducible RL environments.

Keep workers apart

Independent attempts should stay independent, and workers running generated code shouldn’t reach their siblings. Networks partition the swarm, and each worker then reaches the coordinator and nothing else:

boxd machine new coordinator --networks=job-1,job-2,job-3
boxd machine new worker-1 --networks=job-1
boxd machine new worker-2 --networks=job-2
boxd machine new worker-3 --networks=job-3

For untrusted work, create workers with --isolated and they reach nothing of yours beyond networks you grant explicitly. See Sandboxes.

Mind the cost and the cap

Destroy workers when their task ends, since a removed machine costs nothing. Workers you keep for the next batch suspend and hibernate on their own and wake on the next request. Accounts start at 50 concurrent machines, extendable on request, and the coordinator counts too. See Resources and limits.

Getting started

Guides

Use cases

References

Agent swarm intelligence

How it works

Full example

Let the swarm run itself

Production tips

Warm-start workers with a fork

Keep workers apart

Mind the cost and the cap

​How it works

​Full example

​Share state over the private network

​Let the swarm run itself

​Production tips

​Warm-start workers with a fork

​Keep workers apart

​Mind the cost and the cap

How it works

Full example

Share state over the private network

Let the swarm run itself

Production tips

Warm-start workers with a fork

Keep workers apart

Mind the cost and the cap