Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
guest_ip
str
required
IP address assigned to the guest VM.
​
gateway_ip
str
default:"172.16.0.1"
Gateway IP address (host side of the TAP device).
​
netmask
str
default:"255.255.255.0"
Network mask for the guest network.
​
tap_device
str
required
Name of the TAP network device (e.g., “smol0”, “smol1”).
​
guest_mac
str
required
MAC address for the guest network interface.
​
ssh_host_port
int | None
default:"None"
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.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:
  1. TAP Device: A virtual network interface on the host (e.g., smol0)
  2. Guest IP: Private IP address in the 172.16.0.0/16 range by default
  3. Gateway IP: Host-side IP of the TAP device (default: 172.16.0.1)
  4. NAT: Network Address Translation configured via nftables for internet access
  5. 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
This is useful when:
  • 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
To change network settings, create a new NetworkConfig instance.
  • VMConfig - VM configuration including network settings
  • VMInfo - Runtime VM information including network state
  • SmolVM - High-level VM API that uses NetworkConfig internally
Last modified on May 5, 2026