rgrok

README

rgrok

rgrok is a small HTTP tunneling tool. The client connects outward to the server over WebSocket, then the server forwards public HTTP requests through that tunnel to a local port.

Local quick start

Start the server:

go run ./cmd/rgrok server --addr :7000 --domain localhost:7000 --github-client-id "$RGROK_GITHUB_CLIENT_ID" --github-client-secret "$RGROK_GITHUB_CLIENT_SECRET"

Log in with GitHub:

go run ./cmd/rgrok login --server http://localhost:7000

Connect a local app:

go run ./cmd/rgrok connect 1234 --server ws://localhost:7000/api/connect

With a named tunnel:

go run ./cmd/rgrok connect 1234 --server ws://localhost:7000/api/connect --name demo

Then open:

http://demo.localhost:7000

Behind Caddy and Cloudflare

Create a GitHub OAuth app with:

• Homepage URL: https://rgrok.rselbach.com
• Authorization callback URL: https://rgrok.rselbach.com/auth/github/callback
• Device flow enabled

Run the rgrok server on a private local port:

rgrok server --addr 127.0.0.1:7000 --domain rgrok.rselbach.com --scheme https --data /var/lib/rgrok/rgrok.json --github-client-id "$RGROK_GITHUB_CLIENT_ID" --github-client-secret "$RGROK_GITHUB_CLIENT_SECRET"

Use a Caddy site that forwards the apex and wildcard tunnel hosts:

rgrok.rselbach.com, *.rgrok.rselbach.com {
	reverse_proxy 127.0.0.1:7000
}

Log in once on the client:

rgrok login --server https://rgrok.rselbach.com

Connect a client:

rgrok connect 1234 --server wss://rgrok.rselbach.com/api/connect

You can also create named API tokens from the dashboard and pass one directly to the client. API tokens expire after at most 90 days and are stored as hashes on the server.

RGROK_API_TOKEN=... rgrok connect 1234 --server wss://rgrok.rselbach.com/api/connect

Go applications can manage their own tunnel with the public client package:

import rgrokclient "github.com/rselbach/rgrok/client"

tun, err := rgrokclient.Start(ctx, rgrokclient.Config{
	ServerBaseURL: "https://rgrok.rselbach.com",
	Token:         os.Getenv("RGROK_API_TOKEN"),
	Name:          "my-app-dev",
	LocalPort:     1234,
})
if err != nil {
	return err
}
defer tun.Close()

publicBaseURL := tun.PublicURL

For service-style clients, set RGROK_CONFIG while running rgrok login to write the token to a predictable file:

sudo env RGROK_CONFIG=/etc/rgrok/rgrok-client@demo.json rgrok login --server https://rgrok.rselbach.com
sudo chown root:root /etc/rgrok/rgrok-client@demo.json
sudo chmod 0600 /etc/rgrok/rgrok-client@demo.json

The server stores its whitelist, sessions, and default admin user in the JSON file passed with --data. The initial whitelist contains rselbach as an admin. The dashboard is available at https://rgrok.rselbach.com/dashboard.

Sample deployment files for rgrok.rselbach.com live in deploy/:

• deploy/Caddyfile
• deploy/caddy-cloudflare.env
• deploy/rgrok-server.service
• deploy/rgrok-server.env
• deploy/rgrok-client@.service
• deploy/rgrok-client@.env

Current limits

The first implementation forwards one complete HTTP request and response per tunnel message. That keeps the MVP simple, but it means very large or streaming bodies are capped by --max-body. Raw TCP forwarding and chunked streaming can be added on top of the same protocol.