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

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/pgrok-pgrok
Generated for open source discovery and AI-assisted research.

pgrok is a "poor man's ngrok" designed for small teams, offering a multi-tenant HTTP/TCP reverse tunnel solution through SSH remote port forwarding. It provides stable subdomains for every user, gated by your SSO through the OIDC protocol, making it a cost-effective alternative for exposing local development environments to the public internet.

GitHub: https://github.com/pgrok/pgrok
OSRepos URL: https://osrepos.com/repo/pgrok-pgrok

## Summary

pgrok is a "poor man's ngrok" designed for small teams, offering a multi-tenant HTTP/TCP reverse tunnel solution through SSH remote port forwarding. It provides stable subdomains for every user, gated by your SSO through the OIDC protocol, making it a cost-effective alternative for exposing local development environments to the public internet.

## Topics

- go
- pgrok
- reverse-tunnel
- ssh-tunnel
- ngrok-alternative
- sso
- http
- tcp

## Repository Information

Last analyzed by OSRepos: Mon Feb 16 2026 12:01:06 GMT+0000 (Western European Standard Time)
Detail views: 2
GitHub clicks: 3

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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`):**

1.  **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.
2.  **Server Deployment:** Set up `pgrokd` using a [single binary](https://github.com/pgrok/pgrok/blob/main/docs/admin/single-binary.md "pgrokd Single Binary Setup" target="_blank"), [Docker](https://github.com/pgrok/pgrok/blob/main/docs/admin/docker.md#standalone-docker-container "pgrokd Docker Setup" target="_blank"), or [Docker Compose](https://github.com/pgrok/pgrok/blob/main/docs/admin/docker.md#docker-compose "pgrokd Docker Compose Setup" target="_blank").
3.  **Network Security:** Allow inbound requests to port `2222` (and `10000-15000` for TCP tunnels) on your server.
4.  **Reverse Proxy:** Install and configure Caddy 2 to proxy requests to `pgrokd`.
5.  **OIDC Client:** Create an OIDC client in your SSO provider with the Redirect URI set to `http://example.com/-/oidc/callback`.

**Client Setup (`pgrok`):**

1.  **Obtain Token:** Visit your `pgrokd` instance (e.g., `http://example.com`), authenticate with SSO, and obtain your unique token and URL.
2.  **Download Client:**
    *   For Homebrew: `brew install pgrok`
    *   For others, download from the [Releases page](https://github.com/pgrok/pgrok/releases "pgrok Releases" target="_blank").
3.  **Initialize Config:** Run `pgrok init --remote-addr example.com:2222 --forward-addr http://localhost:3000 --token {YOUR_TOKEN}`.
4.  **Launch Client:** Execute `pgrok` or `pgrok http` to start the tunnel.

For detailed instructions and HTTPS setup, refer to the official [pgrok documentation](https://github.com/pgrok/pgrok/tree/main/docs/admin "pgrok Admin Documentation" target="_blank").

## Examples

**HTTP Tunneling:**

To forward requests to `http://localhost:8080`:

sh
pgrok http 8080


**Raw TCP Tunnels:**

To tunnel raw TCP traffic, for example, for a PostgreSQL database on port `5432`:

sh
pgrok tcp 5432


**HTTP Dynamic Forwards:**

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

yaml
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:

1.  Obtain your token and URL from the `pgrokd` web interface.
2.  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.

## Links

*   **GitHub Repository:** [https://github.com/pgrok/pgrok](https://github.com/pgrok/pgrok "pgrok GitHub Repository" target="_blank")
*   **Releases:** [https://github.com/pgrok/pgrok/releases](https://github.com/pgrok/pgrok/releases "pgrok Releases" target="_blank")
*   **Contributing Guide:** [https://github.com/pgrok/pgrok/blob/main/.github/contributing.md](https://github.com/pgrok/pgrok/blob/main/.github/contributing.md "pgrok Contributing Guide" target="_blank")