Jerhemy Waldon
All posts

Notfi Tunnels: self-hosted tunnels to your local services

Notfi Tunnels gives a web app on your laptop, an SSH port on a field device, or a service inside your app a public address, on a server you run yourself.

Notfi Tunnels: self-hosted tunnels to your local services

I like ngrok. Run one command and the app on your laptop has a public URL you can send to a client, point a webhook at, or open on your phone. What I didn’t like was paying for it. The features I actually wanted, like addresses that don’t change every time and more than a tunnel or two, sit behind a subscription.

I wanted an ngrok I didn’t need to pay for. I already had a server, and the core idea isn’t magic, so I built my own.

As for the name: Notfi is “notify” with a couple of letters squeezed out. Naming things is hard, and dropping vowels is a time-honoured shortcut. You say it “No-T-Fi”.

Notfi Tunnels gives something running on your own machine a public address. It works for a web app on your laptop, an SSH port on a device out in the field, or a service inside your own app. It runs on a server you control, and one command opens a tunnel:

$ notfi-tunnel http 3000
Signed in as 'alice'
Inspector:  http://127.0.0.1:4040/?key=Qm9…
Forwarding: https://vya6ib2n.tunnels.notfi.io -> http://localhost:3000   [http-3000]
00:21:28.654  GET     /api/orders                                        200      39 ms

What it does

  • HTTP(S) tunnels, routed by subdomain, including WebSockets, streaming and large uploads.
  • Raw TCP tunnels for SSH, databases and anything else that speaks TCP.
  • A request inspector at localhost:4040 with a live request list, headers and bodies, replay, and copy as curl.
  • Automatic reconnects that keep the same address. The server holds a random address for its owner for 15 minutes after the tunnel drops, so nobody else gets it in the meantime.
  • Fixed subdomains assigned to an account, so --subdomain myapp works for you and is refused for everyone else.
  • Several tunnels at once from a config file with notfi-tunnel start tunnels.json.
  • Self-updating client: notfi-tunnel update checks the download against the release’s checksums and test-runs the new executable before swapping it in.

How it works

The client only ever makes outbound connections, so it works from behind NAT and corporate firewalls. Rather than build a stream multiplexer, I gave each proxied connection its own connection back to the server:

  1. The client opens a long-lived control connection and signs in with its token.
  2. It asks for a tunnel, and the server registers a subdomain (or a TCP port) and replies with the public URL.
  3. When a public request arrives, the server sends a dial message down the control connection.
  4. The client opens a new connection for it, joins it to the session, and from then on that connection carries raw bytes both ways.

Frames on the control connection are a 4-byte length followed by JSON. The client sends a heartbeat every 15 seconds, and either side drops the session after 45 seconds of silence.

The part I’m happiest with is the HTTP side on the server. YARP forwards each request through an HttpMessageInvoker that belongs to the tunnel, and its ConnectCallback hands back a dialled-back data connection instead of a socket. That one hook gives HTTP/1.1 keep-alive pooling, WebSocket upgrades, HTTP/2 on the public side and X-Forwarded-* headers without any extra code.

On the client, HTTP data connections are spliced into a loopback Kestrel server that records each request for the inspector, then forwards it to your app with YARP. TCP connections go straight to the target.

The web UI

The Notfi Tunnels web UI: the Your tunnels page, with counters for open tunnels, requests and traffic, and a card for each connected client showing its tunnels and their throughput.

The server has a web UI at its root domain, written in React and TypeScript. People see their live tunnels with request and traffic counters and a throughput graph, open a tunnel or show its QR code, browse their history, and manage their token and fixed subdomains. Admins get an overview with daily charts, every live session and device (with a disconnect button), users, subdomains, all history, and an activity log of sign-ins and changes. It has light and dark themes.

Accounts are email based. An admin invites someone by email, and they choose their own password. Each account has one token for its clients and devices. Only hashes are stored, plus the token encrypted with the server’s master key so its owner can see it again with their password. Admins can replace a token but never see it.

Devices: open a tunnel only when you need it

The Devices page of the Notfi Tunnels web UI, listing connected devices and the services each one offers.

Run the client as an agent on a device, and nothing is exposed until someone asks for it:

notfi-tunnel agent --service tcp:22 --service http:8080 --name gateway-01

The agent keeps one outbound connection open and sends a tiny keepalive every minute, a few hundred bytes an hour. On the Devices page the device’s owner or an admin picks a service and a time limit, from 15 minutes to 24 hours or none, and clicks Open. The device opens that tunnel itself, and the server closes it when the time is up. The device decides what can be opened: only the services it lists are offered.

The point of agent mode is to set a computer up once and be able to reach it whenever it’s running. On Linux the installer sets the agent up as a systemd service (sudo sh install.sh --agent), so it starts with the machine, connects on its own, and runs as its own unprivileged user in a sandbox.

Tunnels inside your app

For .NET apps there’s a NuGet package, Notfi.Tunnels.Client, so the app can host the tunnel itself with no separate process to spawn:

using Notfi.Tunnels.Client;

await using var tunnel = await NotfiTunnel.StartHttpAsync(5000, new NotfiTunnelOptions { Token = token });
Console.WriteLine(tunnel.PublicUrl);   // https://k3j9x0ab.tunnels.notfi.io

tunnel.RequestCompleted += (_, r) =>
    logger.LogInformation("{Method} {Path} -> {Status}", r.Method, r.Path, r.Status);

The tunnel reconnects by itself after that. For anything that isn’t .NET, notfi-tunnel http 3000 --json prints one JSON event per line on stdout, so any language can drive it.

Built with

  • .NET 10, with Kestrel and YARP for the server and the client.
  • EF Core on SQLite or PostgreSQL, with migrations for both.
  • React and TypeScript (Vite) for the web UI.
  • End-to-end tests that run the server, the client and a backend in one process.
  • Deployment as a systemd service or in Docker on any Linux server, with a step-by-step guide for DigitalOcean.

Try it

Clients for Windows, Linux and macOS are on the releases page. The hosted server at tunnels.notfi.io is in a closed beta for now while I test everything out, but I may open it up later.

As for what’s next for Notfi Tunnels? Whatever tickles my fancy I guess…