Rivet

Operate your plant from a phone – without opening a door into your network

Rivet connects the phone of an authorised person with a controller in the local network. No port forwarding has to be set up on site, and no third-party cloud provider is involved.

For experts: the technology in detail

Everything below can be checked in the repository forgeiec-rivet (branch development, commit 5f01540, 22 Oct 2026). The specification is CLAUDE.md in that repository. We distinguish strictly between implemented (code and tests present), specified (described in CLAUDE.md, not coded) and planned/open (recorded as an open question or as “later”).

Implementation status

Architecture

Ports on the server (from server/contrib/nginx/rivet-stream.conf.in, forgeiec-rivet-wg.service.in, settings.py):

Data paths

1. Browser → gateway web interface https://<device>.<customer>.<zone>.forgeiec.io: nginx reads only the host name (SNI), looks the target up in routes.sqlite and passes the still-encrypted connection with a PROXY protocol header through the uplink to 10.78.x.y:443. TLS ends only in the gateway (rustls); nginx decrypts nothing. This interface is for setup.
2. Phone → service in the LAN (path via the server, CLAUDE.md 4.13): phone WireGuard to UDP 52000 → server interface phones → filter phone_access (phone address, gateway address, TCP port) → SNAT to 10.78.0.2 → uplink → gateway. The gateway accepts from 10.78.0.2 only TCP on ports that have a forward and opens its own TCP connection in the LAN to the target. The phone reaches the service at <uplink-address>:<port>, e.g. http://10.78.0.5:8000, or by name through the mini DNS.
3. Phone → gateway directly (old path, kept until all phones have moved): WireGuard to the gateway’s UDP port on the server → nginx → uplink → phone tunnel in the gateway (10.77.0.0/24, gateway 10.77.0.1) → kernel path (TUN rivet0, nftables DNAT in table ip rivet) or, without CAP_NET_ADMIN, forwarding in userspace (smoltcp).
4. Gateway → portal: HTTPS directly over the internet (not through the uplink), so that registration works without an uplink: register, heartbeat, cert, peers (long poll), uplink-key.

Uplink in the gateway (client/src/net/uplink.rs): one boringtun::noise::Tunn with the server as the only peer over an ordinary outbound UDP socket, behind it a smoltcp stack with the address 10.78.x.y. Only traffic to this address is accepted: from 10.78.0.1 (nginx) TCP 443/80, UDP 51820 and ICMP; from 10.78.0.2 TCP only. Fragments and all other senders are dropped. Keepalive 15 s, MTU 1280. After 180 s without a handshake the gateway opens a new UDP socket and resolves the server name again (against one-way dead NAT mappings on mobile networks). At most 256 concurrent connections in the uplink stack.

Operating modes (field uplink_mode in the portal, models.py): rivet (the Rivet gateway holds the tunnel itself), router (the router’s WireGuard holds the tunnel, a Rivet gateway behind it binds with a code), client (plain WireGuard client without Rivet, no heartbeat). First router target according to CLAUDE.md: Teltonika RUT241, guide docs/router-rutos.md.

Addressing and certificates

Names follow four levels (server/portal/gateways/hosts.py; the base domain is a setting, default forgeiec.io):

The README still shows the older scheme <slug>.<zone>.forgeiec.io; the code uses the one above.

• One wildcard certificate per customer *.<customer>.<zone>.<base>: issued by certbot with certbot-dns-hetzner (DNS-01, ECDSA) from the portal’s venv; renewal by the timer forgeiec-rivet-certs (daily at 03:00 and 15:00).
• Distribution: the deploy hook import_wildcard_cert stores the private key Fernet-encrypted in the portal database and raises the customer’s cert_version. The gateway sees the higher version in the heartbeat response and fetches GET /api/v1/cert (gateway bearer key, response with Cache-Control: no-store). Every fetch is logged in CertFetchLog. Blocked gateways get nothing (API 403).
• Checks in the gateway (client/src/tls.rs) before taking it over: PEM readable, key matches the certificate, name covers the gateway’s own address, not expired, newer than the active one. Then written atomically (key 0600) and activated via ArcSwap without restart. Without a valid wildcard the gateway uses a self-signed certificate (rcgen).
• Portals have their own certificates; a gateway wildcard does not cover them. Emergency rotation per zone in the operator area and in the Django admin (services.emergency_rotation).
• DNS: the portal maintains the records at Hetzner (gateways/dns.py, timer forgeiec-rivet-dns every 15 minutes) and touches only records carrying its own labels.

Identity and authorisation

• Sign-in at the gateway (client/src/auth.rs, web.rs): constant-time comparison (subtle), encrypted session cookie (Rocket secrets) for 12 hours with a prefix of the key hash, so a new key ends all sessions. Failed attempts: 1 s delay, at most 5 per source IP and 30 in total within 5 minutes.
• Registration: POST /api/v1/register without authentication, limited to 10/hour per client IP (FORGEIEC_RIVET_REGISTER_RATE). All other API calls use a bearer key that the portal stores only as a hash.
• Phone setup: QR code and .conf file are created in the browser; the private key never leaves the page. Alternatively a setup link by e-mail: the portal stores only the SHA-256 of the token, valid 7 days, single use.
• Portal accounts are bound to their level; rights per membership: manage phones, gateways, users. The session is valid only for the host where it was created.

Isolation

• What a phone reaches (path via the server): only TCP to (phone address, uplink address of a gateway, port) from the access list. It contains the forwards of all active gateways of its customer; rules with access “service” only for phones with access “service”. Plus the mini DNS at 10.79.0.1:53. Everything else from phones is dropped (fw.rs).
• What a compromised gateway reaches: on the server iifname "uplink" oifname "uplink" drop and iifname "uplink" drop apply: no other gateways, no routing through the server. Towards phones only replies (oifname "phones" only established,related). It does, however, hold its customer’s wildcard key and can impersonate any other gateway of that customer if it can also redirect DNS or traffic (described in CLAUDE.md section 5 as a consciously accepted risk).
• What the server reaches: from the uplink the gateway accepts only the connections listed above; only the forwards from the portal lead into the LAN. Without a forward nothing is forwarded.
• What the server sees: HTTPS to the gateway web interface passes through encrypted (passthrough). The inner traffic of phones on the path via the server, however, it does see, because it decrypts the phone tunnels (CLAUDE.md 4.13: “consciously accepted”). Whatever the application does not encrypt itself is plain text there.
• Overlapping LAN subnets are possible: nothing is routed into any LAN; the server only knows the per-gateway unique 10.78.x.y.

Routing module ngx_stream_rivet_module

Operations

Note: the README still describes the gateway service without nftables and with CAP_NET_BIND_SERVICE only. The current code additionally needs CAP_NET_ADMIN for the kernel path (TUN rivet0, nftables via netlink, no external programs).

Platforms, packages and build

• Built for 12 slots, gateway and server alike: Debian 12/13 and Ubuntu 22.04/24.04, each amd64, arm64 and armhf (client/contrib/slot-build.sh --list). As target hardware for the gateway CLAUDE.md names Debian 12 arm64 and Ubuntu 24.04 armhf. According to its README, the nginx module has only been built and tested against nginx 1.26.3 (Debian 13).
• Packages: forgeiec-rivet (cargo-deb) and forgeiec-rivet-server (CMake/CPack), built natively in a container of the target architecture (podman, qemu-user), not cross-compiled.
• client/deploy.sh: build (default), rebuild, test, run (dry run without root on 8443/8080), peer, package, slot <s|all>, install, restart, clean, help. server/deploy.sh: configure, rebuild, test, run, package, install, restart, clean, slot, help.
• CI: Forgejo workflows client.yml and server.yml, each a matrix over the 12 slots; only main publishes to apt.forgeiec.io.

Quality

The nginx module’s load test (according to its README: 1000 connections with 20 parallel clients, Ryzen 9 9950X in a Podman container) reached about 11,600 connections per second with and without a DB query; the measured latency there is dominated by the Python client, not by the query. There are no other performance or availability figures.

Repository

client/          gateway (Rust): src/{main,auth,config,front,tls,web,setup,sync,portal,forwards}.rs,
                 src/net/{uplink,hub,peers,stack}.rs, src/sys/{tun,rtnl,nft}.rs, templates/, locale/
server/portal/   Django project rivet_server, app gateways (models, API, levels, tests)
server/wg-daemon/  forgeiec-rivet-wg (Rust, netlink, nftables, mini DNS)
server/nginx-module/  ngx_stream_rivet_module (C) with unit, integration and load tests
server/contrib/  systemd units and timers, debconf/postinst, nginx templates
docs/            api-v1.md, betrieb-server.md, router-rutos.md
.github/workflows/  client.yml, server.yml

Threat model (as far as CLAUDE.md states it)

• Shared wildcard key per customer (consciously accepted): whoever extracts it from a gateway can pose as any address under *.<customer>.<zone>, but not as a gateway of another customer or as a portal. Countermeasures in the specification: exploiting it also requires redirecting DNS or traffic; portals under their own certificates; session cookie only for its own host; emergency rotation; blocked gateways receive no new certificates; short Let’s Encrypt lifetimes.
• The server is the trust anchor: it distributes the keys and sees the inner traffic of phones on the path via the server (consciously accepted).
• Router gateways: there, the router’s firewall decides whether the server gets into the LAN, not Rivet.
• Tampered routing database: the nginx module accepts only targets within allow_backend.
• ECH would hide the SNI; therefore no DNS HTTPS records with ECH are published for the Rivet zones.
• UDP blocked or throttled on mobile networks: then the uplink does not come up (open question 11).
• Dependence on the server: without the server there is no remote access; the LAN itself keeps working (open question 8).

Known limits

• Forwards for TCP only; at most 20 rules per gateway; IPv4 only inside the tunnel.
• When a gateway is added to the customer, the phone needs a new configuration (AllowedIPs).
• No fallback when UDP is blocked; no direct access when the server is down.
• Theme takeover on the gateway, alert e-mails, install.sh and the self-test for router gateways are still missing (see implementation status).
• Two phone paths run in parallel until the old one via the gateway is removed.

In contrast to …

The table lists only properties that follow from the architecture.