VM-to-VM networking

A single VM is a starting point. Real agent workloads spawn dozens of them. An orchestrator delegating to workers. A planner spinning up a fresh sandbox per branch of its search. A test matrix running every shard on its own machine. None of that scales if every cross-VM call asks you to plumb auth, SSH keys, secrets, and routing. Every boxd VM ships the same boxd CLI you use on a laptop. From inside a VM it auto-auths. Zero keys, zero tokens, zero config.

# Inside source-vm:
boxd new --name=worker-1
boxd exec worker-1 -- 'cd /app && do-the-thing'
boxd cp ./results worker-1:/uploads/results

How it works (briefly)

Every worker runs a small gateway on its private bridge. That bridge is the default route of every VM on the host. The in-VM CLI talks to the gateway, the gateway looks up the request’s source IP against the VM table, and the matched row’s user_id becomes the auth. No tokens, no SSH keys, no shared secrets. Cross-VM ownership is enforced the same way: a VM can only see, fork, or exec into other VMs owned by the same user. A worker’s bounded by hardware. A fleet of workers stitches together over VXLAN into one flat fabric, so a VM on Worker-A can reach a VM on Worker-B with the same call. The CLI does not care which physical host either VM lives on.

What this enables

Agent fan-out. An orchestrator spawns N worker agents, each in its own VM, each running against its own copy of the codebase. They never stomp on each other. The orchestrator collects results and destroys the workers.
Multi-step pipelines. Step A runs in vm-a, hands its output to vm-b via boxd cp, triggers vm-b’s work with boxd exec. Pause a VM between steps, resume it later, no state lost.
Self-cloning workflows. A VM forks itself, hands a job to the fork, destroys the fork when done. Clean slate per task without rebuilding the environment.
Fleet-level patterns. Test matrices, parallel scrapers, ML batch jobs, distributed builds. Anything that wanted a hundred Linux machines for ten seconds gets it with one for loop.

What you can do from inside a VM

Everything the CLI does, scoped to your VMs only:

boxd list                          # all your VMs
boxd info                          # current VM
boxd new --name=child              # spawn a sibling
boxd fork                          # fork the current VM
boxd exec target -- 'cmd'          # run a command in another VM
boxd cp ./file target:/path        # copy files between VMs
boxd destroy child -y              # destroy

The one thing that doesn’t work from inside a VM is ssh name.boxd.sh. That hostname routes through the public auth gateway by your SSH key, and a VM doesn’t carry your key. Use boxd exec or boxd connect instead.

Reference

Internal CLI

Full command surface of the in-VM boxd.

Fork

Memory, disk, and in-progress work, branched.

​How it works (briefly)

​What this enables

​What you can do from inside a VM

​Reference