Proxmox VE: give your VMs one public address with the TunnelNet agent (tested)
The TunnelNet agent for Proxmox VE gives the virtual machines and containers on one Proxmox host a single fixed public address. People on the internet reach the VMs you choose, on the ports you choose, and the VMs' own internet traffic leaves from that same address. The Proxmox host itself keeps its normal internet line and is never reachable through the TunnelNet address.
Pilot
Proxmox VE support is a pilot. It is not on sale yet. If you would like to try it, ask us.
Tested on
Date: 18 November 2026 · Host: Proxmox VE 8.4.21 (kernel 6.8.12-43-pve) on Debian 12, installed the "Proxmox VE on Debian" way, one node, run as a test machine in our lab · Agent: pve-0.1.0, from the install command in the portal
On the real service: the install command from the portal, the tunnel to our network, a container's traffic leaving from the site's address, the kill switch (hub unreachable, tunnel down), uninstall, and removing the site's connection so the address was released.
On our own test copy of the service (the same software, a private test database): the VM list by name, opening and closing ports to a container and to a VM, stopping the agent, and a host reboot.
All addresses on this page are documentation examples: 203.0.113.29 stands for your TunnelNet address and 198.51.100.77 for the host's own line. 192.168.213.0/24 is the agent's built-in VM network.
What you get
internet ── 203.0.113.29 (your TunnelNet address)
│ tunnel
[Proxmox host] ── own line 198.51.100.77 (unchanged)
│
vmbr-tn 192.168.213.1 (made by the agent, isolated)
├─ CT 101 TEST-web101 192.168.213.10
└─ VM 102 TEST-app102 192.168.213.11
- VMs on
vmbr-tngo out through your TunnelNet address, and you can open ports to them. - The host keeps its own line. Its web screen (8006) and SSH (22) do not answer on the TunnelNet address. We checked both: no answer.
- VMs on your other bridges are not touched.
- One node. This guide covers a single Proxmox host. Clusters are not covered yet (see "Not tested").
Step 1: add the site in the portal and copy the install command
In the portal, add a site and choose Proxmox VE. The Router setup panel shows the install command:
curl -fsSL https://tunnelnet.io/business/proxmox/install.sh | sh -s -- <your code>
The code works once and expires 30 minutes after you make it. If it expires, make a new one in the same panel.
Undo: remove the site in the portal.
Step 2: run it on the Proxmox host
Paste the command into a root shell on the host (the Proxmox web screen's Shell works). Real output from our run:
TunnelNet is set up on this gateway. Your site will show Connected in the portal shortly.
TunnelNet is set up: TEST-4863-pve carries the site now.
Put a VM on the network vmbr-tn with an address in 192.168.213.1/24's range and gateway 192.168.213.1,
then open its ports in the portal. Check any time with: tnet status
It took 14 seconds. The tunnel came up within a minute. tnet status shows what the host is doing:
Agent: running (version pve-0.1.0)
This node: TEST-4863-pve, carries the site
Tunnel: up, last handshake 1 s ago
Address: 203.0.113.29/32
Check-in: 9 s ago (ok)
Ports: 0
The agent makes the bridge vmbr-tn itself, as an extra file in /etc/network/interfaces.d/. It does not edit your own network settings.
If you see this instead:
TunnelNet: this node's /etc/network/interfaces does not read /etc/network/interfaces.d; make the bridge vmbr-tn in Proxmox and run the command again with --bridge vmbr-tn
your /etc/network/interfaces is missing its last line, which a normal Proxmox install has:
source /etc/network/interfaces.d/*
We hit this on our first try. Our host had been built from a cloud image, and its network settings came from that image. Add the line back and run the command again (make a new code if the old one has expired). Do not try to make a bridge called vmbr-tn in the Proxmox screen: Proxmox only accepts names like vmbr1. We tried and it refused (invalid network interface name 'vmbr-tn'). Adding the source line is the fix that worked.
Undo: /var/lib/tunnelnet/tn-pve uninstall (Step 6).
Step 3: put a VM or container on vmbr-tn
In the VM's or container's Network settings, choose bridge vmbr-tn, then give it:
- an address in
192.168.213.2to192.168.213.254 - gateway
192.168.213.1 - a DNS server you like (we used a public one)
What our container looked like to the internet afterwards, next to the host itself:
CT 101 seen as: 203.0.113.29 <- the site's TunnelNet address
host seen as: 198.51.100.77 <- the host's own line, unchanged
Right after the install, expect about 15 to 30 seconds where the VMs have no internet while the agent finishes its first check-in. They never use the host's line in that window.
Undo: set the VM's network card back to your usual bridge (for example vmbr0).
Step 4: open a port to a VM by name
The portal lists the VMs and containers on vmbr-tn by their Proxmox names:
vm {'vmid': 101, 'kind': 'ct', 'name': 'TEST-web101', 'running': True, 'ip': '192.168.213.10'}
vm {'vmid': 102, 'kind': 'vm', 'name': 'TEST-app102', 'running': True, 'ip': '192.168.213.11'}
In Ports, pick the VM, enter the public port and the VM's own port, and save. In our test (public 8083 to TEST-app102 port 8081):
01:46:08 before opening: visitor -> site:8083: (no answer)
01:46:21 visitor -> site:8083: TEST-app102 says hello (8 s after opening)
01:46:33 after closing: visitor -> site:8083: no answer (12 s after closing)
A port to the container answered 3 seconds after opening. While those ports were open, the host's own 22 and 8006 still gave no answer on the site's address.
Two things to know:
- A VM shows its address once it has sent some traffic. Without the QEMU guest agent, the address comes from what the host has seen on
vmbr-tn. A VM that was just started may show no address for a moment. Ping anything from inside it and it appears. - Open only the ports you need, and limit who can reach them in the same screen if you can.
Undo: delete the rule in Ports. It stopped answering 12 seconds later in our test.
Step 5: the kill switch
VMs on vmbr-tn only ever reach the internet through the tunnel. We broke the tunnel three ways and checked what the container looked like each time.
On the real service:
before: CT 101 203.0.113.29 | host 198.51.100.77
hub unreachable: CT 101 none | host 198.51.100.77 (x3, 13 s apart)
back: CT 101 203.0.113.29 (16 s after the line came back)
tunnel down: CT 101 none | host 198.51.100.77 (x2)
back: CT 101 203.0.113.29 (18 s after the tunnel came back)
On our test copy, with the agent service stopped (systemctl stop tunnelnet-agent), the tunnel, the forwarding and the VMs' gateway were all removed and the container again had no internet, never the host's line. After a host reboot, everything came back by itself: the host was up in 51 seconds and the container was out through the site's address 71 seconds after the reboot.
"None" is the point: a VM on vmbr-tn is either on your TunnelNet address or offline. It never leaks out of your host's own line.
Step 6: remove it
On the host:
# /var/lib/tunnelnet/tn-pve uninstall
Left the TunnelNet network vmbr-tn in place: still used by ct 101,vm 102.
TunnelNet is removed from TEST-4863-pve.
It removes only what TunnelNet made: the tunnel, its rules and routes, its files, and the service. It puts forwarding back to off. It leaves vmbr-tn in place while any VM still uses it, and says which ones. Move those VMs to another bridge and run it again to remove the bridge too. We checked afterwards: no tunnel, no TunnelNet files, no rules, forwarding off, and the container had no internet until we moved it to another bridge.
Uninstall removes the agent from your Proxmox. Your address stays yours until you remove the site in the portal. That is on purpose, so a reinstall gets the same address back. In our run the site still showed in the portal after the uninstall, as expected. To finish our test we removed the site's connection on our side with our own admin tool, and the address was released within a minute. For you, the portal's remove step does this. We did not press that button in this run.
What we did not test
- Clusters. The installer has the code for several nodes sharing one address, with one node carrying it at a time. We have not proven that a second node takes over, so this guide is for one node only.
- Opening ports on the real service. We opened and closed ports on our test copy. On the real service we tested the install, the address, the kill switch and removal.
- IPv6, and a host installed from the Proxmox ISO. Our host was Proxmox VE installed on Debian 12. The ISO normally writes the
sourceline from Step 2 for you. - Speed. We did not measure throughput through the tunnel in this run.
- VMs leaving by the host's own line on purpose. That is not offered.
Limits
- One address per site. Every VM on
vmbr-tnshares it, so two VMs cannot both use public port 443. Use different public ports, or one VM in front of the others. - Your VMs see visitors as coming from us, not from the visitor's own address.
- Outgoing mail on port 25 is blocked. Use a mail service.