---

smuf exposes a local port on a public URL — like ngrok, but yours: no quotas, no limits, on your own server.

localhost:3000  ◄─────►  https://a3f1c9.yourdomain.com

---

Deploy on Railway

One-click deploy smuf-server to Railway:

Once deployed, the server URL and auth token are set via Railway's environment variables (see Configuration below). Then connect with the client from any machine.

---

Installation

Option A: Download a binary (recommended)

Go to Releases and download the binary for your OS.

Option B: Docker

docker compose up -d

Option C: Build from source

You'll need Go 1.21+.

git clone https://github.com/cdrusu/smuf.git && cd smuf
go build -o smuf-server ./cmd/smuf-server
go build -o smuf        ./cmd/smuf

---

Usage

First time: run without arguments and the wizard will set everything up:

./smuf-server   # on the server
./smuf --setup  # on your machine

After that:

./smuf 3000                    # exposes localhost:3000
./smuf 3000 4000 5000          # multiple ports at once
./smuf --sub myapp 3000        # fixed URL: myapp.yourdomain.com
./smuf --tcp 22                # pure TCP tunnel (SSH, DB, etc.)

Output:

  Tunnel ready!

  Local   → http://localhost:3000
  Public  → https://a3f1c9.yourdomain.com

  Press Ctrl+C to stop

---

Dashboard

While the server is running, open in your browser:

http://yourdomain.com:8080/

It is designed in HashiCorp style: dark #0d0e12 background, system-ui font, cards with micro-shadows and blue accent (#1060ff).

Shows all active tunnels with:

• Tunnel type (HTTP / TCP)
• Public URL
• Local port and client IP
• Uptime

Updates every 5 s. The JSON endpoint is at /_smuf/tunnels.

---

Configuration

Everything goes through environment variables (or a .env file next to the binary).

Server (smuf-server)

Client (smuf)

Server .env example:

SMUF_DOMAIN=yourdomain.com
SMUF_AUTH_TOKEN=a-long-secret-token
# SMUF_HTTPS=true
# SMUF_ACME_EMAIL=you@email.com

Client .env example:

SMUF_SERVER=yourdomain.com:7000
SMUF_AUTH_TOKEN=a-long-secret-token
# SMUF_SUBDOMAIN=myapp

Generate a secure token with openssl rand -hex 32

---

How it works

smuf 3000  ──TCP──►  smuf-server :7000
                           │
              "PORT 3000 SUB myapp"  →  "OK myapp https://myapp.yourdomain.com"
                           │
                   yamux (multiplexing)
                           │
          request → myapp.yourdomain.com → yamux stream → localhost:3000

Uses hashicorp/yamux to multiplex multiple HTTP requests over a single TCP connection.

---

Roadmap

• Automatic HTTPS with Let's Encrypt
• Token authentication
• Per-IP rate limiting
• Real-time web dashboard (HashiCorp style)
• Multiple tunnels per process
• Custom subdomain
• WebSockets
• TCP tunnels (not only HTTP)
• Official Docker image
• Pre-compiled binaries
• Server-Sent Events (SSE)

---

Project structure

smuf/
├── cmd/
│   ├── smuf/           # Client (your machine)
│   └── smuf-server/    # Server (your VPS)
└── internal/
    ├── tunnel/         # Registry + BufConn
    ├── wizard/         # Interactive setup
    └── logger/         # Timestamped logging

---

Contributing

Found a bug or have an idea? Open an issue or submit a pull request.

---