yatun is an open-source TCP reverse tunneling tool (think ngrok / cloudflared) written in Go. It exposes local services to the internet through a public relay server.

┌──────────┐    TCP     ┌────────────────┐   yamux   ┌──────────┐   TCP   ┌─────────┐
│ Internet │───────────▶│  yatund        │◀═════════▶│  yatun   │────────▶│ local   │
│ Client   │ random port│  (relay server)│  session  │  (agent) │ :port   │ service │
└──────────┘            └────────────────┘           └──────────┘         └─────────┘

I wanted to understand how tools like ngrok and cloudflared work under the hood, so I built one.

1. Agent opens a TCP connection to yatund:5678, upgrades to a yamux session.
2. Agent sends connection details (subdomain) over the first yamux stream.
3. Server opens an ephemeral TCP port, sends the public address back to the agent, starts a heartbeat ping loop.
4. When an internet client connects to the open port, the server opens a new yamux stream toward the agent.
5. Agent dials localhost:<port> and bidirectionally copies data between the yamux stream and the local service.

Each agent gets its own TCP port on the server. All connections to that port are multiplexed over a single yamux session to the agent, which forwards them to the local service.

# For the client
go install github.com/KatIsCoding/yatun/cmd/yatun@latest
# For the server
go install github.com/KatIsCoding/yatun/cmd/yatund@latest

Pre-built binaries are available on the Releases page.

Expose a local service through the public relay at yatun.snowdev.one — no server setup needed.

# Expose local port 8080
yatun --port 8080

The agent opens a TUI showing connection status, the public address, active connections, and ping latency.

• Press q or Ctrl+C to quit.
• Press c to copy the public address to your clipboard.

Use --server to point at a different relay:

yatun --port 8080 --server your-server.com

Run your own relay on a machine with a public IP.

# Optional: set your public domain so addresses are reported as domain.com:port
export DOMAIN=https://tunnel.example.com

yatund

The server listens on port 5678 for agent connections.

A Dockerfile and compose file are provided for a simple example of how the relay could be deployed with docker.

cd deploy
docker compose up --build

The compose file requires an .env file in deploy/. Example:

# Domain for address reporting (optional)
DOMAIN=https://tunnel.example.com

# TLS (set to 1 to enable)
TLS=1

# Paths to your certificate files on the host (For the purposes of the example in the deploy/ folder)
HOST_CER_FILE=/root/.acme.sh/example.com_ecc/fullchain.cer
HOST_KEY_FILE=/root/.acme.sh/example.com_ecc/example.com.key

The server looks for certificates at certs/cert.cer (fullchain) and certs/cert_key.key (private key) inside the container by default (can be changed over env vars). The compose file maps host paths to those locations.

Messages between agent and server use a simple binary format:

[1 byte: type][2 bytes: payload length (big-endian uint16)][N bytes: JSON payload]

yatun/
├── cmd/
│   ├── yatun/              # Agent binary
│   │   └── main.go
│   └── yatund/             # Server binary
│       └── main.go
├── deploy/
│   ├── Dockerfile
│   └── docker-compose.yml
├── internal/
│   ├── config/             # Server configuration from env vars
│   ├── message/            # Wire protocol encoding / decoding
│   ├── server/             # Server-side tunneling logic
│   ├── tls/                # TLS certificate loading and connection wrapping
│   └── tui/                # Bubble Tea TUI for the agent
├── ssl/
    └── install.sh          # Helper to install acme.sh

MIT