tunnl

Open-source, self-hosted webhook development platform. Capture, inspect, replay, and debug HTTP webhooks through secure tunnels.

Website | Documentation | Changelog

---

TUI Inspector

Real-time split-pane terminal inspector. Webhooks appear as they arrive — select any request to see headers, body, and response. Press r to replay.

---

MCP Integration for AI Agents

MCP (Model Context Protocol) lets AI assistants like Claude Desktop and Cursor introspect live data from your tools. With tunnl mcp, your AI can read real webhook payloads while debugging — no copy-paste from logs.

tunnl mcp exposes 8 tools via the Model Context Protocol. Claude, Cursor, and other MCP-compatible agents can list tunnels, query captured payloads, replay requests, and search webhook history — without leaving the editor.

---

Features

• Persistent request history — 30-day retention in PostgreSQL; browse past webhooks after the fact
• Real-time terminal inspector — split-pane TUI shows live request/response detail as traffic arrives
• One-click request replay — resend any captured request without touching the origin
• Wildcard subdomain routing — <your-subdomain>.yourdomain.com out of the box
• WebSocket passthrough — tunnel bidirectional WebSocket connections, not just HTTP
• HTTP/2 support — full h2c proxying through the tunnel protocol
• TCP tunnel support — forward raw TCP traffic, not just HTTP
• MCP server for AI coding agents — tunnl mcp exposes tunnel tools to Claude, Cursor, and other MCP-compatible agents
• API key authentication — machine-friendly tokens for CI/CD and automation
• Custom subdomain reservations — claim stable subdomains that persist across sessions
• IP allowlisting and traffic policies — restrict inbound tunnel traffic by IP range

---

Quick Start

Self-Hosted (Docker Compose)

git clone https://github.com/sqoia-dev/tunnl.git
cd tunnl
cp .env.example .env          # edit DB_PASSWORD, JWT_SECRET, DOMAIN
docker compose up -d

The server starts on http://localhost:8080. Point a reverse proxy (Caddy, nginx) at it and configure wildcard DNS for your domain. See the self-hosting guide for the full walkthrough.

Install the CLI

curl -fsSL https://tunnl.sh/install.sh | sh
tunnl login --server https://your-tunnl-instance.example.com
tunnl --port 3000

Your local server is now reachable at https://<your-subdomain>.your-tunnl-instance.example.com.

---

Architecture

The server is a Go (Gin) application backed by PostgreSQL. Caddy handles TLS termination and wildcard subdomain routing. The CLI connects to the server over a WebSocket control channel; inbound HTTP requests are serialized as JSON messages and forwarded to the CLI, which proxies them to the local port and sends the response back.

Internet -> Caddy (TLS) -> tunnl-server -> WebSocket -> tunnl CLI -> localhost:PORT

The wire protocol is defined in internal/protocol/messages.go. Both the server and CLI import this package from the same module — there is no protocol duplication.

---

Repository Structure

tunnl/
├── cmd/
│   ├── server/         # Server entrypoint
│   └── tunnl/          # CLI entrypoint
├── internal/
│   ├── protocol/       # Shared WebSocket message types
│   ├── server/         # Server packages (handlers, proxy, models, db, ...)
│   └── cli/            # CLI packages (client, tui, inspector, mcp, ...)
├── web/
│   └── api/            # API route registration
├── Dockerfile
├── docker-compose.yml
└── Makefile

---

Building from Source

Go 1.24 is required.

# Build both binaries
make all

# Build individually
make server   # -> bin/tunnl-server
make cli      # -> bin/tunnl

# Run tests
make test

# Lint
make lint

---

Configuration

The server is configured via environment variables. Key variables:

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
JWT_SECRET	Yes	Secret used to sign auth tokens
DOMAIN	Yes	Root domain for wildcard subdomains
PORT	No	HTTP listen port (default: 8080)
SELF_HOSTED_MODE	No	Set true to grant all users Pro limits
MAX_TUNNELS	No	Override max tunnels per user

See the configuration reference for the full list.

---

Contributing

1. Fork the repo and create a branch from main
2. Make your changes — go test ./... must pass
3. Run golangci-lint run ./... and fix any new lint issues
4. Open a pull request with a clear description of what and why

Please open an issue before starting large changes so we can discuss the approach first.

---

License

MIT — see LICENSE