Skip to main content
Every SmolVM sandbox gets its own private network connection. The sandbox can reach the internet, but it cannot talk to other sandboxes or access host network interfaces directly. This page explains how the networking works and what you can configure.

​
How it works

When SmolVM creates a sandbox, it sets up a dedicated virtual network interface (called a TAP device) for that sandbox. The sandbox receives a private IP address and uses NAT to reach the internet through your host’s network connection. Each sandbox receives:
  • Guest IP: an address in the 172.16.0.2 – 172.16.0.255 range
  • Gateway: 172.16.0.1 (the host side of the TAP device)
  • Netmask: 255.255.255.0 (/24)
SmolVM assigns these automatically. You do not need to configure networking for most use cases.

​
Sandbox isolation

Sandboxes are isolated from each other by default. SmolVM adds a firewall rule that drops all traffic between TAP devices, so one sandbox cannot reach another: 
# This rule is added automatically
nft add rule inet smolvm_filter forward iifname "tap*" oifname "tap*" counter drop
Each sandbox can:
  • Access the internet via NAT
  • Be reached from the host via port forwarding
  • Not communicate directly with other sandboxes
Sandboxes can access the internet by default. If you need to restrict outbound traffic, add firewall rules on your host. See security model for details.

​
TAP devices

A TAP device is a virtual network interface that connects a sandbox to the host networking stack. SmolVM creates one TAP device per sandbox and removes it when the sandbox is deleted. The lifecycle of a TAP device:
  1. Create — SmolVM runs ip tuntap add to create a virtual interface
  2. Configure — assigns the host-side IP and brings the link up
  3. Route — adds a host route so packets reach the sandbox
  4. Cleanup — deletes the TAP device when the sandbox stops
All of this is handled automatically. You only need to interact with TAP devices if you are debugging networking issues.

​
NAT and firewall rules

SmolVM uses nftables to manage NAT and firewall rules. It creates two tables:
  • ip smolvm_nat — handles NAT (masquerade for outbound traffic, DNAT for port forwarding)
  • inet smolvm_filter — handles forwarding rules and sandbox isolation
When a sandbox starts, SmolVM:
  1. Enables IP forwarding on the host (net.ipv4.ip_forward=1)
  2. Adds a masquerade rule so outbound traffic appears to come from the host
  3. Adds a forwarding rule to allow traffic from the sandbox’s TAP device to the internet
  4. Adds an isolation rule to block sandbox-to-sandbox traffic
You can inspect the active rules at any time: 
sudo nft list table ip smolvm_nat
sudo nft list table inet smolvm_filter

​
Port forwarding

SmolVM supports two types of port forwarding to reach services running inside a sandbox.

​
SSH port forwarding

SSH access is set up automatically when a sandbox starts. SmolVM forwards a host port to port 22 inside the guest using nftables DNAT rules. You can connect manually: 
ssh -p <host_port> root@localhost
Or use the SDK, which handles SSH connections for you through vm.run().

​
Application port forwarding

To access a web server, database, or other service running inside a sandbox, use expose_local(): 
from smolvm import SmolVM

with SmolVM() as vm:
    vm.run("python3 -m http.server 8080 &")
    host_port = vm.expose_local(guest_port=8080, host_port=18080)
    print(f"Service available at http://localhost:{host_port}")
expose_local() only binds to 127.0.0.1 (localhost). Services are not exposed to your network. If you need external access, set up additional forwarding outside of SmolVM.
See the port forwarding guide for more examples including automatic port allocation, multiple forwards, and troubleshooting.

​
Network prerequisites

SmolVM needs the following tools installed on your host (Linux only):
  • ip (from iproute2) — manages TAP devices and routes
  • nft (from nftables) — manages NAT and firewall rules
  • sudo access for networking commands
The smolvm setup command installs these automatically. You can verify your setup with: 
smolvm doctor

​
Troubleshooting

Check that IP forwarding is enabled and NAT rules are in place:
# Should return 1
cat /proc/sys/net/ipv4/ip_forward

# Enable manually if needed
sudo sysctl -w net.ipv4.ip_forward=1

# Check NAT rules exist
sudo nft list table ip smolvm_nat
Install the missing package:
# Ubuntu/Debian
sudo apt install iproute2 nftables

# Fedora/RHEL
sudo dnf install iproute nftables
Run the SmolVM system setup to configure sudo permissions:
sudo ./scripts/system-setup.sh --configure-runtime
Check that route_localnet is enabled for the TAP device and forwarding rules exist:
# Should return 1
cat /proc/sys/net/ipv4/conf/tap0/route_localnet

# Check forwarding rules
sudo nft list chain inet smolvm_filter forward
Also verify that the service inside the sandbox is binding to 0.0.0.0, not 127.0.0.1.
If cleanup failed, remove the device manually:
# List TAP devices
ip link show | grep tap

# Delete manually
sudo ip link delete tap0

# Or clean up all SmolVM resources
smolvm cleanup --all

​
Next steps

Last modified on April 6, 2026