Files
hermenix/docs/NETWORK.md
T
2026-10-09 14:35:12 -04:00

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

  1. 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.
  2. Set options above, sudo nixos-rebuild switch (brief network drop).
  3. Verify: hermenix vm ssh; inside, ip -4 addr shows 10.77.0.2 and 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

  • hostLanAddress is 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.nix won't take a bridged address; upgrade the image or apply that config inside the VM first.
  • Drop publish entries if you return to NAT mode; they do nothing while bridged.