Network configuration

Every Celesto sandbox gets a private network connection. Internet access is open by default, and you can turn it off or restrict supported Linux networks to specific destinations. Most applications need no network setup.

How it works

QEMU uses slirp by default on macOS and Linux. Slirp is a user-mode network built into QEMU, so it needs no administrator privileges or host network device. Firecracker and explicit QEMU qemu_network="tap" use a TAP device on Linux. A TAP device is a virtual network interface connecting one sandbox to the host. The sandbox receives a private IP address and uses network address translation (NAT) to reach the internet through the host. On the Linux TAP path, 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)

Celesto assigns these automatically. QEMU only uses this path when you explicitly select TAP.

Sandbox isolation

Sandboxes are isolated from each other by default. On Linux TAP, Celesto adds a firewall rule that drops traffic between sandbox interfaces:

# This rule is added automatically
nft add rule inet smolvm_filter forward iifname "tap*" oifname "tap*" counter drop

With default open access, a sandbox can:

Access the internet via NAT
Be reached from the host via port forwarding
Not communicate directly with other sandboxes

Use Network controls to turn outbound access off or allow specific destinations. QEMU off mode works with the default network on macOS and Linux; restricted IPv4 destinations require explicit TAP networking on Linux.

TAP devices

A TAP device is a virtual network interface that connects a sandbox to the host networking stack. Celesto creates one TAP device per sandbox and removes it when the sandbox is deleted. The lifecycle of a TAP device:

Create — Celesto runs ip tuntap add to create a virtual interface
Configure — assigns the host-side IP and brings the link up
Route — adds a host route so packets reach the sandbox
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.

Linux TAP NAT and firewall rules

For Firecracker and QEMU TAP, Celesto 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, Celesto:

Enables IP forwarding on the host (net.ipv4.ip_forward=1)
Adds a masquerade rule so outbound traffic appears to come from the host
Adds a forwarding rule to allow traffic from the sandbox’s TAP device to the internet
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

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

SSH port forwarding

When a sandbox uses SSH, Celesto makes its SSH port reachable from the host. QEMU slirp uses QEMU’s built-in host forwarding. Linux TAP uses a localhost nftables rule. You can connect manually with the assigned host port:

ssh -p <host_port> root@localhost

Or use the SDK, which handles the configured SSH or vsock command connection through vm.run().

Application port forwarding

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

from celesto import Celesto

with Celesto() 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}")

QEMU slirp uses QEMU’s built-in forwarding. Linux TAP uses a localhost nftables rule. Both keep the service private to your machine. The following diagram shows the Linux TAP path:

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

Applications should listen on 0.0.0.0 inside the sandbox. For an application that listens only on guest 127.0.0.1, pass guest_loopback=True; this uses an SSH tunnel. See the port forwarding guide for more examples including automatic port allocation, multiple forwards, and troubleshooting.

Linux TAP prerequisites

Firecracker and QEMU TAP need the following tools on Linux:

ip (from iproute2) — manages TAP devices and routes
nft (from nftables) — manages NAT and firewall rules
sudo access for networking commands

The celesto setup command installs these automatically. You can verify your setup with:

celesto doctor

Troubleshooting

Sandbox has no internet access

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

'ip' or 'nft' command not found

Install the missing package:

# Ubuntu/Debian
sudo apt install iproute2 nftables

# Fedora/RHEL
sudo dnf install iproute nftables

Permission denied on TAP creation

Run the Celesto system setup to configure sudo permissions:

sudo ./scripts/system-setup.sh --configure-runtime

Port forwarding not working

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.

TAP device persists after sandbox deletion

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 Celesto resources
celesto sandbox delete --all --force

Next steps

Review the security model
Choose your backend (Firecracker vs. QEMU)
Read the architecture overview

Get Started

Features

Guides

Architecture

Operations

Network configuration

How it works

Sandbox isolation

TAP devices

Linux TAP NAT and firewall rules

Port forwarding

SSH port forwarding

Application port forwarding

Linux TAP prerequisites

Troubleshooting

Next steps

​How it works

​Sandbox isolation

​TAP devices

​Linux TAP NAT and firewall rules

​Port forwarding

​SSH port forwarding

​Application port forwarding

​Linux TAP prerequisites

​Troubleshooting

​Next steps

How it works

Sandbox isolation

TAP devices

Linux TAP NAT and firewall rules

Port forwarding

SSH port forwarding

Application port forwarding

Linux TAP prerequisites

Troubleshooting

Next steps