Reverse tunnel

The tunnel lets a ci-agent box that has no public IP — one behind NAT, a home router, or a locked-down office network — serve its apps on the public internet through another ci-agent box that does have a public IP.

The private box never opens an inbound port. It dials out to the public box and keeps the connection open; visitors reach the public box, and their traffic is passed straight through to the private box.

What this means. Normally a server can only be reached if the internet can connect to it. A box behind NAT can’t be reached that way. The tunnel flips it around: the private box connects out to a public helper, and that helper forwards visitors back down the same connection. No port-forwarding, no public IP on the private box.

The two boxes (roles)

Every ci-agent install has a Role, set on the Tunnel page in the sidebar (/tunnel). While tunneling is off, the page shows two cards — pick the one that matches this box:

Role What the box becomes
Off A normal ci-agent. No tunneling. (The default.)
Online (relay) A public box that is both a normal ci-agent and a relay for private boxes.
Local (dial out) A private/NAT’d box that dials out to an Online box.

Picking a card only opens that role’s settings — nothing changes yet. Each role’s screen has an On/Off switch at the top: turn it on to activate the role, turn it off to go back to a plain ci-agent (and back to the two cards). You can fill in everything before switching on; staged tunnels, routes and connection settings take effect the moment the switch flips. While a role is active, a link above its screen still opens the other role’s settings, so you can stage or tidy them without turning anything off — switching on from there replaces the active role directly.

You set the role in the UI; the agent applies it. No reinstall and no command-line flags.

Important: the relay never decrypts your traffic

TLS (HTTPS) is terminated on the private (Local) box, where your certificates live. The Online box forwards the raw encrypted stream and never decrypts it — it only reads the hostname the visitor asked for, to decide which tunnel to send them down. The public box needs no certificate for your tunneled apps.

What Online mode does to the public box

When you switch a box to Online, the ci-agent relay takes over the public ports 443, 80 and 7000:

The box’s own nginx is quietly moved to loopback (127.0.0.1:8443 / :8080) so the relay can own the public front door. Your existing sites keep working; they are only affected if you deliberately route one of their exact hostnames down a tunnel (which the UI blocks — see below).

Switching to Online also tries to open UFW ports 7000, 443 and 80 for you. If port 7000 is still closed, the Tunnel page warns:

Port 7000 is closed in the firewall — agents can’t connect. Open it on the Firewall page.

Set up a tunnel

You work on both boxes: mint a tunnel token on the Online box, then paste it into the Local box.

On the Online (public) box

  1. Pick the Online card and turn the switch on. (You can also stage steps 2–4 first and switch on afterwards. While the role is off, the page says: This role is off — tunnels and routes staged here take effect the moment you switch it on above.)
  2. Under Add tunnel, fill:
    • Id — a short name the Local box will present (e.g. box-a). 1–63 characters: a–z, 0–9, -, _, ..
    • Label (optional) — a human note, e.g. Warehouse edge box. Click Add tunnel.
  3. A card appears with three values — Tunnel id, Token, and Relay fingerprint — and this warning:

    Copy these now — the token is shown only once and is never stored in cleartext.

    Copy all three. You need them on the Local box. The relay fingerprint is also always shown at the top of the Tunnels (registered agents) card, but the token is not. (If you lose the token, click Rotate token on the tunnel’s row to mint a new one. The same card appears with the new token. The old token stops working immediately, so update the Local box too.)

  4. Under Add route, tell the relay which hostnames belong to this tunnel:
    • Hostname — an exact host (app.example.com) or a leftmost wildcard (*.example.com). It must not clash with a hostname this box already serves itself: a project domain, a project’s default subdomain, or the admin panel’s own domain. A wildcard is refused if it would catch any of them.
    • Tunnel — pick the tunnel you just added.
    • PROXY protocol (optional) — see below. Click Add route. Add as many routes as you like; anything not routed here is served by this box’s own nginx. If the Local box has not connected yet, you see Route added — note: tunnel ‘…’ is not connected. That is fine; the route goes live once it connects.
  5. Point DNS for each routed hostname at this (the Online box’s) public IP.

screenshot: the Online role screen with the Tunnels and Routes tables

Managing tunnels and routes later:

On the Local (private) box

  1. Pick the Local card. The switch stays disabled until the connection details below are saved — fill them in first. Next to the switch, a hint lists what is missing, for example Still needed: token, relay fingerprint — save below to enable.
  2. In the Connection settings card, enter the values from the Online box:
    • Online server — the relay’s address as host:port, e.g. relay.example.com:7000. The relay always listens on port 7000, so use 7000 unless something in between (a NAT rule, for example) forwards a different port to it.
    • Tunnel id — the id you created (e.g. box-a).
    • Token — the one-time token. (Leave blank to keep the current one.)
    • Relay fingerprint — the SHA-256 fingerprint from the Online box. This pins the relay’s certificate; the agent refuses to connect if it doesn’t match, so a fake relay can’t impersonate yours.
    • Ports (default 443,80) — an advisory list for the Online operator. Keep 80 so per-host HTTPS certificate renewal can work through the tunnel. (The relay forwards each visitor to whichever port they arrived on regardless.) Whatever the relay asks for, the Local box only connects visitors to its own nginx on 443 and 80. Nothing else that listens on the box, such as the panel’s own port or a database bound to 127.0.0.1, can be reached through the tunnel.
  3. Click Save settings, then turn the switch on. The box dials out and connects. You can save the form in several visits; until everything is in, the message says Settings saved — still needed before switching on: ….

A Connection status card on the Local box shows connected (with the time since) or disconnected, plus a Reconnect now button and the last error if a connection failed.

Certificates through the tunnel

Your tunneled apps keep their certificates on the Local box, exactly like a normal ci-agent — issue and renew them on the Local box’s Certificates page. Because port 80 is relayed down the tunnel, Let’s Encrypt HTTP-01 renewals keep working automatically. The Online box needs no certificate for tunneled hostnames.

Statuses you’ll see

PROXY protocol

By default, a tunneled app sees the connection as coming from the relay, not from the real visitor. Turn on PROXY protocol (per route on the Online box, and matched in Local settings) to have the relay prepend a small header so the private box can recover the real visitor IP. When you enable it on the Local box you must also set the Relay IP (the Online box’s public IP), which is trusted for set_real_ip_from. Without it, saving fails with Enter the relay’s IP address to enable PROXY protocol.

You can switch PROXY protocol for an existing route at any time with the PROXY checkbox in the Routes table on the Online box.

The Online box’s own sites and admin panel always get the real visitor IP, with no setting to change. The relay passes the visitor’s address to the box’s nginx, so login limits and API limits count each visitor separately. (Without this, every visitor would look like 127.0.0.1, and one client could fill the limits for everyone.)

Exception: if your global nginx snippet (Host page) sets its own real_ip_header, for example behind a CDN, ci-agent leaves the real-IP setup to you and adds none of its own. To use the relay’s visitor address, add set_real_ip_from 127.0.0.1; and real_ip_header proxy_protocol; there instead. The same applies to a Local box with PROXY protocol on.

The relay also protects itself from slow or flooding visitors. A visitor must send the start of its request (the TLS hello or HTTP headers) within 10 seconds, or the relay closes the connection. One address can have at most 32 connections at that stage, and all visitors together at most 512.

Gotcha. Once PROXY protocol is on for the Local box, its nginx expects the header on every connection — so the box is then reachable only through the tunnel. Direct connections to it will break. Enable it on both ends or neither.

Common problems and fixes