Overview
NetworkConfig is a Pydantic model that defines the network configuration for a microVM. It specifies the guest IP, gateway, TAP device, MAC address, and optional SSH port forwarding.
This model is immutable (frozen) and is typically created automatically by SmolVM when starting a VM.
Attributes
IP address assigned to the guest VM.
Gateway IP address (host side of the TAP device).
netmask
str
default:"255.255.255.0"
Network mask for the guest network.
Name of the TAP network device (e.g., “smol0”, “smol1”).
MAC address for the guest network interface.
Optional host TCP port forwarded to guest SSH port 22.When set, you can SSH to the guest using ssh -p <ssh_host_port> root@localhost.
Usage
Creating a NetworkConfig
from smolvm import NetworkConfig
network = NetworkConfig(
guest_ip="172.16.0.2",
gateway_ip="172.16.0.1",
netmask="255.255.255.0",
tap_device="smol0",
guest_mac="AA:FC:00:00:00:01",
ssh_host_port=2222
)
print(f"Guest IP: {network.guest_ip}")
print(f"Gateway: {network.gateway_ip}")
print(f"TAP device: {network.tap_device}")
Accessing Network Info from a VM
from smolvm import SmolVM, VMConfig
config = VMConfig(
kernel_path="/path/to/vmlinux",
rootfs_path="/path/to/rootfs.ext4"
)
vm = SmolVM(config)
vm.start()
info = vm.info
if info.network:
print(f"VM IP: {info.network.guest_ip}")
print(f"TAP device: {info.network.tap_device}")
if info.network.ssh_host_port:
print(f"SSH port: {info.network.ssh_host_port}")
Using with the High-Level API
from smolvm import SmolVM
with SmolVM() as vm:
# Network is automatically configured
ip = vm.get_ip()
print(f"VM IP: {ip}")
# Access the full network config
info = vm.get_info()
if info.network:
print(f"Gateway: {info.network.gateway_ip}")
print(f"MAC address: {info.network.guest_mac}")
Network Architecture
SmolVM uses the following networking setup:
- TAP Device: A virtual network interface on the host (e.g.,
smol0)
- Guest IP: Private IP address in the
172.16.0.0/16 range by default
- Gateway IP: Host-side IP of the TAP device (default:
172.16.0.1)
- NAT: Network Address Translation configured via nftables for internet access
- Port Forwarding: Optional TCP port forwarding for SSH access
Default IP Range
By default, SmolVM assigns guest IPs from 172.16.0.0/16:
- Gateway:
172.16.0.1
- Guest VMs:
172.16.0.2, 172.16.0.3, etc.
SSH Port Forwarding
When ssh_host_port is set, you can access the guest via localhost:
# If ssh_host_port is 2222
ssh -p 2222 root@localhost
- The guest IP is not directly routable
- You want to expose SSH on a predictable port
- You’re running behind a firewall
Example: Custom Network Configuration
from smolvm import NetworkConfig
# Create a custom network config
network = NetworkConfig(
guest_ip="172.16.100.50",
gateway_ip="172.16.100.1",
netmask="255.255.255.0",
tap_device="smol-custom",
guest_mac="AA:FC:00:00:01:23",
ssh_host_port=3333
)
print(f"Guest: {network.guest_ip}")
print(f"Gateway: {network.gateway_ip}")
print(f"SSH: localhost:{network.ssh_host_port}")
Immutability
NetworkConfig is a frozen Pydantic model, meaning it cannot be modified after creation:
network = NetworkConfig(
guest_ip="172.16.0.2",
tap_device="smol0",
guest_mac="AA:FC:00:00:00:01"
)
# This will raise a ValidationError
network.guest_ip = "172.16.0.3" # Error: frozen model
NetworkConfig instance.
- VMConfig - VM configuration including network settings
- VMInfo - Runtime VM information including network state
- SmolVM - High-level VM API that uses NetworkConfig internally