> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# VM to VM

> How a VM talks to other VMs you own.

A VM you own can create and drive other VMs. Every boxd VM ships the same `boxd` CLI you use on a laptop, and from inside a VM it authenticates automatically, with nothing to configure first.

```bash theme={"theme":"github-dark"}
# Inside source-vm:
boxd machine new worker-1
boxd machine exec worker-1 -- 'cd /app && do-the-thing'
boxd machine cp ./results worker-1:/uploads/results
```

## How it works

From inside a VM, boxd already knows which machine the call is coming from, so it authenticates you as that machine's owner automatically. The machine's own identity is the credential, so there is nothing to pass around. Ownership is enforced on every call. A VM can only see, fork, or exec into other VMs **you** own.

That holds no matter how many VMs you run. By default all your VMs, within your organization, 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, you can configure that through tag based networks.

## What you can do from inside a VM

Everything the CLI does, scoped to your VMs only:

```bash theme={"theme":"github-dark"}
boxd machine list                   # all your VMs
boxd info                           # current VM
boxd machine new child              # spawn a sibling
boxd machine fork                   # fork the current VM
boxd machine exec target -- 'cmd'   # run a command in another VM
boxd machine cp ./file target:/path # copy files between VMs
boxd machine remove child -y        # destroy
```

The one thing that doesn't work from inside a VM is `ssh name.boxd.sh`. That hostname resolves to the proxy's public edge, and a VM 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 VM's services directly.

## Reach another VM over the network

`boxd machine exec` and `boxd machine cp` cover running commands and moving files. When you want one VM to talk to another's **running service** (an API, a database, a dev server), resolve it by name. Inside any VM, `<vmname>.boxd` resolves to that VM's private IP:

```bash theme={"theme":"github-dark"}
# inside any of your VMs:
curl http://worker-1.boxd:8000/health
psql -h db.boxd -U postgres
```

Name resolution is private to you. Only VMs **you** own resolve, so names and IPs stay invisible across tenants, and `worker-1.boxd` resolves identically from any of your VMs, wherever the target machine happens to be. Names answer with a short TTL of 30 seconds, and only the bare `<vmname>.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.

## Tag based networks

By default every VM you own is on one network and reaches every other. Give a VM one or more **networks** and it leaves that default pool:

> Two VMs can reach each other if they **share at least one network**, or if **neither has any network**.

```bash theme={"theme":"github-dark"}
boxd machine new api --networks=backend
boxd machine new db  --networks=backend,analytics
boxd machine new web                          # no networks

boxd machine networks api backend,cache       # replace the whole set
boxd machine networks api --clear             # back to the default 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, `<name>.boxd` DNS, and `boxd machine exec` / `cp` alike, so there's no back door 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 lives outside the default network entirely, other isolated machines stay unreachable from it, and it ships without the in-VM CLI. See [sandboxes](/use-cases/sandboxes).

<Note>
  `<vmname>.boxd` is for VM-to-VM traffic over the private network. Public clients still reach a VM at its `<vmname>.boxd.sh` HTTPS domain through the proxy.

  Don't confuse this with the `<vmname>.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 VM from outside. This is real DNS, used by one VM to reach another over the private network.
</Note>
