grain
cc03a05
Install

guides

Overlay network (guest↔guest L2)

Share an L2 segment across grain VMs with network overlay mode.

By default each grain VM uses SLIRP (user networking): isolated from other VMs, with host→guest port forwards.

For multi-VM labs that need guest-to-guest connectivity, set network: overlay. grain attaches a second NIC using QEMU’s multicast socket backend so VMs on the same host join a shared L2 segment (230.0.0.1:4242) while keeping SLIRP for SSH and published ports.

Enable

Per VM

bash 
grain new -n a --network overlay --wait agent
grain new -n b --network overlay --wait agent

Config default (~/.grain/config.yaml)

yaml 
network: overlay   # or slirp

What you get

InterfaceRole
First NIC (SLIRP)Host access, hostfwd, proxy via 10.0.2.2
Second NIC (overlay)Guest↔guest on the shared multicast LAN

Inside the guest, configure addresses on the second interface yourself (static IP, mDNS, etc.). grain does not run DHCP on the overlay.

Security note

Overlay places every participating VM on one shared L2. There is no guest↔guest firewall from grain.

The guest agent listens on :7475 without authentication. On SLIRP-only VMs that is reachable from the host only via loopback hostfwd (or vsock). On overlay, a peer can open TCP to another guest’s agent on the overlay interface and run exec/shell/fs as that agent.

Network modeGuest↔guest L2Peer can hit other guests’ :7475 agent?
slirp (default)NoNo (agent only via host loopback hostfwd / vsock)
overlayYes (multicast)Yes — treat all overlay VMs as one trust domain

Do: use overlay for cooperative multi-VM labs (k3s nodes, service meshes, integration tests) under one operator.
Don’t: put untrusted or multi-tenant workloads on the same overlay; don’t publish agent port 7475 beyond loopback.

Host→guest SSH and published ports still use SLIRP hostfwd bound to 127.0.0.1. Overlay does not open those to the LAN. Full trust model: Security model.

When you create with --network overlay, the daemon logs a one-time Warn that peers share L2 and can reach each other’s agents.

Limits

  • Same host only (multicast socket, not a routable multi-host fabric)
  • Firewall/OS multicast restrictions can block the overlay
  • Firecracker backend does not use this path
  • No multi-tenant isolation between overlay peers (see security note above)

See also