pgrok: A Multi-Tenant HTTP/TCP Reverse Tunnel Solution via SSH

Introduction

pgrok is an open-source, multi-tenant HTTP/TCP reverse tunnel solution that leverages SSH remote port forwarding. Billed as a "poor man's ngrok," it's specifically designed for small teams that need to expose their local development environments to the public internet. It stands out by offering stable subdomains for individual users, secured by your own Single Sign-On (SSO) provider via the OIDC protocol.

This project aims to provide a simpler, more controlled alternative to commercial services for internal team use, allowing developers, community managers, sales, and PMs to easily share their local work without deep server operations knowledge. It requires you to bring your own domain name and SSO provider, offering a tailored and cost-efficient solution.

Installation

Setting up pgrok involves configuring both a server component (pgrokd) and a client (pgrok).

Prerequisites:

A domain name (e.g., example.com)
A server (VPS, dedicated) with a public IP address
An SSO provider that supports OIDC (e.g., Google, Okta, GitLab)
A PostgreSQL server

Server Setup (pgrokd):

DNS Records: Add A records for your domain and a wildcard subdomain (e.g., example.com and *.example.com) pointing to your server's public IP.
Server Deployment: Set up pgrokd using a single binary, Docker, or Docker Compose.
Network Security: Allow inbound requests to port 2222 (and 10000-15000 for TCP tunnels) on your server.
Reverse Proxy: Install and configure Caddy 2 to proxy requests to pgrokd.
OIDC Client: Create an OIDC client in your SSO provider with the Redirect URI set to http://example.com/-/oidc/callback.

Client Setup (pgrok):

Obtain Token: Visit your pgrokd instance (e.g., http://example.com), authenticate with SSO, and obtain your unique token and URL.
Download Client:
- For Homebrew: brew install pgrok
- For others, download from the Releases page.
Initialize Config: Run pgrok init --remote-addr example.com:2222 --forward-addr http://localhost:3000 --token {YOUR_TOKEN}.
Launch Client: Execute pgrok or pgrok http to start the tunnel.

For detailed instructions and HTTPS setup, refer to the official pgrok documentation.

Examples

HTTP Tunneling:

pgrok http 8080

Raw TCP Tunnels:

pgrok tcp 5432

HTTP Dynamic Forwards:

Configure dynamic_forwards in your pgrok.yml to route specific paths to different local addresses:

dynamic_forwards: |
  /api http://localhost:8080
  /hook http://localhost:8080

This will forward requests to /api and /hook to http://localhost:8080, while other requests go to your forward_addr.

Vanilla SSH Client:

Since pgrok uses the standard SSH protocol, you can also use a vanilla SSH client:

Obtain your token and URL from the pgrokd web interface.
Run ssh -N -R 0::3000 example.com -p 2222 and enter your token as the password.

Why Use pgrok?

pgrok addresses the common pain points of high costs associated with stable subdomains and SSO integration in other tunneling solutions. It's built for teams who value simplicity and efficiency, especially when exposing local services for testing, demos, or collaboration.

Cost-Effective: Avoids the high enterprise tier costs of commercial alternatives by allowing you to use your existing infrastructure and SSO provider.
Simplified UX: Offers a "Copy, paste, and run" experience, making it accessible even for team members without extensive server operations knowledge.
Stable Subdomains & SSO: Provides consistent URLs for users, secured by your organization's SSO, which is crucial for internal team workflows.
Flexibility: Supports both HTTP and raw TCP tunneling, with advanced features like dynamic HTTP forwards.