Skip to main content
A machine you own can create and drive other machines. Every machine ships with an in-machine boxd CLI, and from inside a machine it authenticates automatically, with nothing to configure first. The samples on this page run inside a machine unless they say otherwise.

How it works

From inside a machine, boxd already knows which machine the call is coming from. The machine’s own identity is the credential, so there is nothing to pass around. Inside a private machine, the CLI and the SDKs act as that machine’s owner, fenced to its organization. Inside a shared machine, they act for the org’s shared machines only. Access is enforced on every call, so a machine can only see, fork, or exec into machines its owner can access. That holds no matter how many machines you run. By default all your machines within an org share one private network, so a call from one reaches any other of yours the same way, whether you run two machines or two hundred. When you want less reach than that, use networks. The private network spans one region, and the in-machine boxd works in its machine’s region. Between regions, machines reach each other over a machine’s HTTPS URL, a raw port forward, or your own WireGuard or Tailscale.

What you can do from inside a machine

The in-machine CLI covers the machines you can access:
boxd info and boxd machine fork without a machine name exist only in the in-machine CLI. Its command set differs from the laptop CLI’s. boxd machine cp between machines is capped at 1 GB per file. The one thing that doesn’t work from inside a machine is ssh <machine>.boxd.sh. That hostname resolves to the proxy’s public edge, and a machine doesn’t carry your SSH key. Use boxd machine exec or boxd connect to run commands, or the internal DNS name below to reach a machine’s services directly.

Reach another machine over the network

boxd machine exec and boxd machine cp cover running commands and moving files. When you want one machine to talk to another’s running service (an API, a database, a dev server), resolve it by name. Inside any machine, <machine>.boxd resolves to that machine’s private IP:
Name resolution is private to you. Only machines you own resolve, so names and IPs stay invisible across tenants, and worker-1.boxd resolves identically from any of your machines, wherever the target machine happens to be. Names answer with a short TTL of 30 seconds, and only the bare <machine>.boxd form resolves, without sub-labels. Everything that isn’t a .boxd name is forwarded to a normal upstream resolver, so regular internet DNS keeps working unchanged.

Networks

By default every machine you own is on one network and reaches every other. Give a machine one or more networks and it leaves that default pool.
Two machines can reach each other if they share at least one network, or if neither has any network.
api and db reach each other over backend. Neither can reach web, and web can’t reach them. The partition applies to direct connections, <machine>.boxd DNS, and boxd machine exec and cp alike, so there is no way around it. Changes take effect immediately. This is useful when machines working on the same job shouldn’t see each other. Give each one its own network, shared only with the machine that coordinates them, and they stay mutually unreachable even though they’re all yours. boxd machine new --isolated goes further. An isolated machine is in no default network, it can never reach another isolated machine and no other isolated machine can reach it, and it ships without the in-machine CLI. See Sandboxes.
<machine>.boxd is for machine-to-machine traffic over the private network. Public clients still reach a machine at its <machine>.boxd.sh HTTPS domain through the proxy.Don’t confuse this with the <machine>.boxd SSH alias the CLI writes on your laptop. The name is the same but the two are different things. That alias is a local ~/.ssh/config shortcut for ssh-ing into a machine from your laptop. This is real DNS, used by one machine to reach another over the private network.