#Networking

Every module gets an isolated network shared by its VMs. By default, the build creates a single VPC with one subnet and internet access, which is fine for most cases. Declare extra network structure only when you need something more.

A network has three layers:

• VPCs isolate one network from another. Two VPCs cannot reach each other unless you bridge them. Internet access is a per-VPC setting.
• Subnets live inside a VPC. A subnet has a CIDR (when managed) and a DHCP setting.
• NICs live on a VM and attach the VM to a subnet. Each NIC pins to a PCI slot (1–9) and can also carry a static IP, MAC, and model.

#In the editor

There are two places to look:

• The top-level Network section lists the module's VPCs and Subnets. Click + VPC or + Subnet to add one.
  • On a VPC, Internet is None, Build only, or Always. Build only gives the build phase internet (for apt, downloads, package installs) but isolates clones from the public internet. Always leaves internet on for both build and clones.
  • On a subnet, Mode is Managed or Unmanaged. Managed subnets fill in CIDR, VPC, DHCP, and DNS. Unmanaged subnets ignore those fields (see Managed vs unmanaged subnets below).
• Inside each VM, the Network Interfaces section lists the VM's NICs. Each NIC has a Slot (1–9 PCI slot), a Subnet (a dropdown of the subnets you declared), and optional IP, MAC, and Model. Click + NIC to add one; the editor picks the lowest free slot. Up to nine NICs per VM.

#Defaults (no network configured)

If you leave the Network section empty, the build creates a single VPC, a single subnet, and internet access. Every VM gets one NIC connected to that subnet via DHCP.

#One subnet, custom CIDR

network:
    subnets:
        - name: lan
          cidr: '10.0.0.0/24'
vms:
    - name: builder
      # ...
      nics:
          - name: nic1
            slot: 1
            subnet: lan
            ip: '10.0.0.10'

If you specify any nics, list them all. There is no "automatic NIC" once you start declaring them.

#Multiple subnets in one VPC

network:
    subnets:
        - name: mgmt
          cidr: '10.0.0.0/24'
          dns: '8.8.8.8,1.1.1.1'
        - name: data
          cidr: '10.0.1.0/24'
          dhcp: false
vms:
    - name: multi-nic
      nics:
          - name: nic1
            slot: 1
            subnet: mgmt
          - name: nic2
            slot: 2
            subnet: data
            ip: '10.0.1.50'
            mac: '52:54:00:ab:cd:ef'

Any subnet without an explicit vpc ends up in the auto-created VPC.

#Multiple VPCs

Two VPCs are isolated from each other unless you bridge them. Useful for modeling a public/private split.

network:
    vpcs:
        - name: public
          internet: true
        - name: private
          internet: false
    subnets:
        - name: pub-subnet
          vpc: public
          cidr: '10.0.0.0/24'
        - name: priv-subnet
          vpc: private
          cidr: '10.0.1.0/24'
vms:
    - name: web
      nics:
          - name: nic1
            slot: 1
            subnet: pub-subnet
            ip: '10.0.0.10'
    - name: db
      nics:
          - name: nic1
            slot: 1
            subnet: priv-subnet
            ip: '10.0.1.10'

#NIC settings

nics:
    - name: nic1 # required schema label; arbitrary but conventionally `nic{slot}`
      slot: 1 # PCI slot 1-9; pins NIC identity across downstream builds
      subnet: lan
      ip: '10.0.0.10' # optional; auto-assigned if omitted on a DHCP subnet
      mac: '52:54:00:...' # optional
      model: 'virtio' # virtio | e1000 (default) | e1000e | rtl8139 | pcnet | ne2k_pci

NIC slot pins the NIC to a specific PCI address on the VM. The same logical NIC then keeps the same PCI address across the base build and every downstream build that reuses the image — so persisted per-adapter state (Windows adapter rename, static IP, DHCP server binding, AD DNS binding) lands on the same interface. The visual editor exposes slot as a 1–9 dropdown; in YAML it is an integer.

name is a required label used internally to key the VMI interface and network entries against each other. It does not control the in-guest interface name or the PCI placement (slot does both, indirectly). The visual editor generates it as nic{slot}; hand-authored YAML can use any DNS-label name.

NIC model matters for OS compatibility:

• e1000 (default): every modern OS has an in-box driver. Safe for first boots, especially Windows installs before the virtio driver is loaded.
• virtio: much faster, but the guest must already have the netkvm/virtio_net driver. For Windows builds: install the virtio driver first, reboot, then optionally switch.
• The others are legacy and rarely needed.

#Managed vs unmanaged subnets

By default, every subnet you declare is managed: the platform runs OVN with IPAM and DHCP, hands out the addresses you assign, and attaches its relay pod so the controller can SSH/WinRM into the VM to run provisioners.

Setting Mode to Unmanaged (or unmanaged: true in YAML) opts a subnet out of all of that. The subnet becomes a plain Linux-bridge L2 segment with no IPAM, no DHCP, and no relay attachment. This is the right choice when something inside a VM needs to serve DHCP itself, for example a Windows DHCP server build, or a router VM that owns its own LAN.

network:
    subnets:
        - name: mgmt
          cidr: '10.0.0.0/24'
        - name: lab
          unmanaged: true
vms:
    - name: dhcp-server
      nics:
          - name: nic1
            slot: 1
            subnet: mgmt # managed: controller reaches us here
          - name: nic2
            slot: 2
            subnet: lab # unmanaged: we serve DHCP on this segment

Constraints to keep in mind:

• Every VM that runs provisioners needs at least one NIC on a managed subnet. The controller drives provisioners over SSH/WinRM through the relay pod, which is only attached to managed subnets. A VM whose NICs are all on unmanaged subnets is unreachable from the controller and the build will hang waiting for the communicator.
• cidr, dhcp, dns, and vpc are ignored on unmanaged subnets. There is no IPAM to configure; addressing is whatever the guests negotiate over the L2 segment.
• NIC ip is ignored on unmanaged subnets. The form shows unmanaged in place of the IP field for this reason. Set the address inside the guest instead.

#Internet access

Each VPC has an internet flag. When true, the VPC has NAT egress to the public internet and 8.8.8.8 / 1.1.1.1 DNS. When false, the VPC is fully isolated from the internet (but VMs can still reach each other).

A common pattern is to enable internet during the build (you need to download packages) but disable it on the resulting clones. In the editor, pick Build only on the VPC's Internet dropdown. See Build-only overrides for the YAML form of the same setting.

#Inter-VM communication

VMs in the same module can reach each other over the declared network using the IP addresses you assign. Multi-VM modules are described in Multi-VM builds.