#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 — that's fine for most cases. Declare network only when you need something more.

#Defaults (no network block)

A single VPC, a single subnet, internet access on. Every VM in the module 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: eth0
            subnet: lan
            ip: '10.0.0.10'

If you specify any nics, list them all — there's 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: eth0
            subnet: mgmt
          - name: eth1
            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: eth0
            subnet: pub-subnet
            ip: '10.0.0.10'
    - name: db
      nics:
          - name: eth0
            subnet: priv-subnet
            ip: '10.0.1.10'

flowchart TB Internet((Internet)) subgraph publicVPC[public VPC - internet on] pubSubnet[pub-subnet<br/>10.0.0.0/24] end subgraph privateVPC[private VPC - internet off] privSubnet[priv-subnet<br/>10.0.1.0/24] end webVM[web VM] dbVM[db VM] Internet -.-> publicVPC pubSubnet -- "eth0 NIC<br/>10.0.0.10" --> webVM privSubnet -- "eth0 NIC<br/>10.0.1.10" --> dbVM

#NIC settings

nics:
    - name: eth0 # also the interface name inside the VM
      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 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.

#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: enable internet during the build (you need to download packages), but disable it on the resulting clones. See Build-only overrides.

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