4.4 KiB
Network
Default model and reachability table: CONCEPTS.md.
Mode matrix
| NAT (default) | Bridged (network.bridged = true) |
|
|---|---|---|
| Guest address | 10.77.0.2 on isolated bridge |
service net plus fixed LAN address |
| Inbound from LAN / internet | only via publish |
every port the guest opens |
| Guest → public internet | yes (masqueraded) | yes (L2 / LAN gateway) |
| Guest → private LAN | lanAccess / allowLan only |
same gates |
| Guest → host services | hostAccess + host cache on 10.77.0.1 |
same over service net |
publish |
DNAT on uplink | ignored |
Guest → a service on your LAN
services.hermenix.lanAccess = [
{ address = "192.168.1.50"; port = 11434; } # ollama
{ address = "192.168.1.50"; port = 9000; proto = "udp"; }
];
One destination:port per entry, punched through the RFC1918 drop. Traffic is masqueraded; the peer sees the host's address.
allowLan = true opens all private space at once. Prefer lanAccess — an
agent that goes wrong should not wander.
Guest → a service on the host
services.hermenix.hostAccess = [ { port = 8188; } ];
The service must bind somewhere the guest can see. 127.0.0.1 will not work
(guest arrives on the bridge). Bind to 10.77.0.1 (bridge only) or
0.0.0.0:
services.comfyui.listenAddress = "10.77.0.1";
From the guest: http://10.77.0.1:8188.
Often better than GPU passthrough when you only need the capability over HTTP — see PASSTHROUGH.md.
Expose a guest service
Guest side — agent opens its firewall in /etc/nixos:
networking.firewall.allowedTCPPorts = [ 22 8080 ];
Host only — already allowed (outbound host→guest):
curl http://10.77.0.2:8080
Wider network (NAT mode):
services.hermenix.publish = [
{ hostPort = 8080; guestPort = 8080; }
];
DNATs the uplink port and opens the forward rule. Ports need not match. A published port only answers on the host's own addresses (LAN, tailscale, and so on). Traffic to other addresses the host routes for, such as containers with their own LAN IPs, is left alone. Publishing is the one change that lets the outside world start conversations with the agent's machine — put TLS/auth in front of anything that isn't a toy.
Bridged mode (guest on the LAN)
Guest becomes a first-class LAN device: fixed address, reachable on any port it opens, outbound still gated.
services.hermenix.network = {
bridged = true;
externalInterface = "enp191s0";
lanAddress = "10.0.12.50"; # guest's fixed LAN address
hostLanAddress = "10.0.12.10"; # this host's LAN address
lanGateway = "10.0.12.1";
lanPrefixLength = 24;
# lanDns = [ "1.1.1.1" ]; # optional; defaults to lanGateway
};
The bridge absorbs the uplink. The host-side DHCP on the bridge reserves
lanAddress for the guest MAC; the guest stays a plain DHCP client. The
bridge clones the uplink MAC so the host keeps its LAN identity. Guest DHCP
broadcast never leaves the bridge.
Switching over
- Pick free addresses for guest, host (use the host's existing LAN address if reserved), and gateway. Keep them outside the DHCP pool or reserve them.
- Set options above,
sudo nixos-rebuild switch(brief network drop). - Verify:
hermenix vm ssh; inside,ip -4 addrshows10.77.0.2and the LAN address. From another LAN device:ssh hermes@<guest-lan-address>.
Switching back
bridged = false and rebuild. Guest DHCP finds no server on the isolated
bridge and falls back to the static route via the host. No guest-side change.
Gotchas
hostLanAddressis a static LAN claim — reserve it.- Uplink network config is replaced by the bridge-port role while bridged.
- Older guest images without DHCP-on-NIC in
guest/common.nixwon't take a bridged address; upgrade the image or apply that config inside the VM first. - Drop
publishentries if you return to NAT mode; they do nothing while bridged.