4.2 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. 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.