How It Works

The Problem

You have software running on a cloud server — an AI agent, a crawler, an automation tool — that needs to interact with the web. But websites see a datacenter IP address and treat it like a bot. Captchas, blocks, rate limits, geo-restrictions.

Meanwhile, you have devices with perfectly normal internet connections — your phone on LTE, your laptop on home WiFi, a Raspberry Pi at a friend's place. These are the IPs that websites trust, because millions of regular people use them every day.

The Solution

Restunnel lets your cloud server route traffic through your own personal devices. Your server's requests exit through your phone's mobile connection or your home broadband. The website on the other end sees a normal residential IP, not a datacenter.

Architecture

Restunnel uses a star topology. Each hub sits at the center with exit nodes connecting inbound. Hubs are independent — they don't know about each other.

Server A (Hetzner)                    Server B (AWS)
┌────────────────────────┐     ┌────────────────────────┐
│  Your Software         │     │  Your Crawler          │
│       │                │     │       │                │
│       ▼                │     │       ▼                │
│  Restunnel Hub A       │     │  Restunnel Hub B       │
│  socks5://localhost:1080│     │  socks5://localhost:1080│
└───────┬────────────────┘     └──────────┬─────────────┘
        │                                 │
        │    Encrypted tunnels            │
        │    (exit nodes connect out)     │
        │                                 │
   ┌────┴─────────────────────────────────┴────┐
   │                                            │
   ▼                                            ▼
📱 Phone (LTE)                          💻 Laptop (Home WiFi)
   Connected to: Hub A + Hub B              Connected to: Hub A

Hub

A single binary that runs on your server alongside your software. It has three responsibilities:

• Tunnel endpoint (:9000) — Listens for incoming connections from exit nodes. Uses a Noise protocol handshake that silently drops unauthenticated connections. Maintains persistent encrypted tunnels with keepalive. Multiplexes many TCP streams over a single tunnel per exit node.

• Local proxy (:1080 SOCKS5, :1081 HTTP CONNECT) — Binds to localhost only. Any software on the server can use it as a standard proxy. Routes requests through connected exit nodes. Supports named node selection.

• Dashboard (:8080) — Binds to localhost only, accessed via SSH tunnel. Shows connected exit nodes. Manage nodes and generate QR codes for pairing.

Exit Nodes

Apps running on your personal devices. They connect outbound to hubs — they never listen on any port. Zero inbound attack surface.

Request Flow

How an HTTPS request flows through the system:

Your Software              Hub                     Phone (Exit Node)
     │                      │                           │
     │ SOCKS5 CONNECT       │                           │
     │ example.com:443      │                           │
     │─────────────────────►│                           │
     │                      │  CONNECT example.com:443  │
     │                      │──────────────────────────►│
     │                      │                           │
     │                      │                           │ TCP connect
     │                      │                           │ to example.com
     │                      │                           │
     │                      │       CONNECT_OK          │
     │                      │◄──────────────────────────│
     │   SOCKS5 OK          │                           │
     │◄─────────────────────│                           │
     │                      │                           │
     │ TLS ClientHello      │         DATA              │
     │─────────────────────►│──────────────────────────►│──► example.com
     │                      │                           │
     │                      │         DATA              │
     │◄─────────────────────│◄──────────────────────────│◄── example.com
     │ TLS ServerHello      │                           │

Nobody sees plaintext. The hub and exit node relay encrypted TLS bytes. The target website sees the phone's residential IP making a normal HTTPS connection.

Pairing

Setup is a one-time QR code scan:

1. The hub generates a one-time enrollment token (valid for 15 minutes)
2. The token is encoded in a QR code on the dashboard
3. The exit node app scans the QR code
4. A Noise protocol handshake establishes mutual authentication
5. The hub stores the node's public key — future reconnections use this key directly

After enrollment, the token is burned. The exit node authenticates via its cryptographic keypair on every reconnection. No passwords, no bearer tokens on the wire.

Security

Restunnel is designed for users who will install it and forget about it. Every default is the safe option.

• Closed network — The hub is invisible to unauthorized devices. No valid key = no response. Port scanners see nothing.
• No open relay — Even if misconfigured, the system cannot become a relay for third parties. Every proxy connection requires an authenticated exit node.
• Private IP blocking — Exit nodes refuse connections to RFC1918/RFC6598 private ranges. Your server cannot reach devices on the exit node's local network.
• Localhost-only services — The proxy and dashboard bind to 127.0.0.1. No config option to expose them without an explicit override.
• Hardware-backed keys — Device private keys stored in Android Keystore, macOS Keychain, or iOS Secure Enclave where available.

For the full security model, see Security.

What It's Not

• Not a VPN. It doesn't route all your traffic through anything.
• Not a commercial proxy network. Your hubs, your devices, your IPs.
• Not multi-user. One owner across all hubs and exit nodes.
• Not an anonymity tool. It uses your own real IPs.
• Not a mesh network. Star topology — hub in the center, exit nodes around it.