https://github.com/pgrok/pgrok Skip to content Toggle navigation Sign up * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code + Explore + All features + Documentation + GitHub Skills + Blog * Solutions + For + Enterprise + Teams + Startups + Education + By Solution + CI/CD & Automation + DevOps + DevSecOps + Case Studies + Customer Stories + Resources * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles + Repositories + Topics + Trending + Collections * Pricing [ ] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this organization All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} pgrok / pgrok Public * Notifications * Fork 11 * Star 510 Poor man's ngrok - a multi-tenant HTTP reverse tunnel solution through SSH remote port forwarding License MIT license 510 stars 11 forks Star Notifications * Code * Issues 0 * Pull requests 3 * Actions * Security * Insights More * Code * Issues * Pull requests * Actions * Security * Insights pgrok/pgrok This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags Name already in use A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? Cancel Create 1 branch 5 tags Code * Local * Codespaces * Clone HTTPS GitHub CLI [https://github.com/p] Use Git or checkout with SVN using the web URL. [gh repo clone pgrok/] Work fast with our official CLI. Learn more. * Open with GitHub Desktop * Download ZIP Sign In Required Please sign in to use Codespaces. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching Xcode If nothing happens, download Xcode and try again. Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit @unknwon unknwon chore: fix typos in README ... 5194387 Mar 12, 2023 chore: fix typos in README 5194387 Git stats * 40 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .github ci: fix CodeQL permission March 12, 2023 13:52 cmd chore: fix typo and unused args March 12, 2023 12:37 internal ci: add CodeQL scanning (#14) March 12, 2023 13:50 templates pgrokd: embed templates (#5) March 10, 2023 17:01 .deepsource.toml Revert "Update .deepsource.toml" March 12, 2023 13:55 .editorconfig auth: implement OIDC flow (#3) March 9, 2023 23:49 .gitignore all: use YAML as the config format and support dynamic forwards (#6) March 10, 2023 17:32 .golangci.yml Initial commit March 8, 2023 20:57 .goreleaser.pgrok.yml goreleaser: add Homebrew tap March 11, 2023 14:22 .goreleaser.pgrokd.yml ci: disable changelog from goreleaser March 11, 2023 10:58 LICENSE Initial commit March 8, 2023 20:57 README.md chore: fix typos in README March 13, 2023 04:20 Taskfile.yml pgrokd: implement database layer (#4) March 10, 2023 16:48 codecov.yml Initial commit March 8, 2023 20:57 go.mod pgrok: use github.com/urfave/cli/v2 March 10, 2023 19:39 go.sum pgrok: use github.com/urfave/cli/v2 March 10, 2023 19:39 pgrok.example.yml all: use YAML as the config format and support dynamic forwards (#6) March 10, 2023 17:32 pgrokd.exmaple.yml README: add How section March 11, 2023 00:15 View code [ ] pgrok - Poor man's ngrok What? Why? How? Set up the server (pgrokd) Set up the client (pgrok) Override config options Dynamic forwards Vanilla SSH Explain it to me Sponsors Credits License README.md pgrok - Poor man's ngrok Sourcegraph What? The pgrok is a multi-tenant HTTP reverse tunnel solution through remote port forwarding from the SSH protocol. This is intended for small teams that need to expose the local development environment to the public internet, and you need to bring your own domain name and SSO provider. It gives stable subdomain for every user, and gated by your SSO through OIDC protocol. Think this as a bare-bone alternative to the ngrok's $65/user/month enterprise tier. Try to put this behind a production system will blow up your SLA. For individuals and production systems, just buy ngrok, it is still my favorite. Why? Stable subdomains and SSO are two things too expensive. Why not just pick one from the Awesome Tunneling? Think broader. Not everyone is a dev who knows about server operations. For people working as community managers, sales, and PMs, booting up something locally could already be a stretch and requiring them to understand how to set up and fix server problems is a waste of team's productivity. Copy, paste, and run is the best UX for everyone. How? Before you get started, make sure you have the following: 1. A domain name (e.g. pgrok.dev, this will be used as the example throughout this section). 2. A server (dedicated server, VPS) with a public IP address (e.g. 111.33.5.14). 3. An SSO provider (e.g. Google, Okta, Keycloak) that allows you to create OIDC clients. 4. A PostgreSQL server (bit.io, Cloud SQL, self-host). Note HTTPS for the web and proxy server is not required for this to work, while recommended if possible. Examples in the section all use HTTP. Set up the server (pgrokd) 1. Add the following DNS records for your domain name: 1. A record for pgrok.dev to 111.33.5.14 2. A record for *.pgrok.dev to 111.33.5.14 2. Create a pgrokd.yml file: external_url: "http://pgrok.dev" web: port: 3320 proxy: port: 3000 scheme: "http" domain: "pgrok.dev" sshd: port: 2222 database: host: "localhost" port: 5432 user: "REDACTED" password: "REDACTED" database: "pgrokd" identity_provider: type: "oidc" display_name: "Google" issuer: "https://accounts.google.com" client_id: "REDACTED" client_secret: "REDACTED" field_mapping: identifier: "email" display_name: "name" email: "email" # # The required domain name, "field_mapping.email" is required to set for this to work. # required_domain: "example.com" 3. Download the latest version of the pgrokd archive from the Releases page. 4. Launch the pgrokd in background (systemd, screen, nohup). 1. By default, pgrokd expects the pgrokd.yml is available in the working directory. Use --config flag to specify a different path for the config file. 5. Alter your network security policy (if applicable) to allow inbound requests to port 2222 from 0.0.0.0/0 (anywhere). 6. Download and install Caddy 2 on your server, and use the following Caddyfile config: http://pgrok.dev { reverse_proxy * localhost:3320 } http://*.pgrok.dev { reverse_proxy * localhost:3000 } 7. Create a new OIDC client in your SSO with the Redirect URI to be http://pgrok.dev/-/oidc/callback. Set up the client (pgrok) 1. Go to http://pgrok.dev, authenticate with your SSO to obtain the token and URL (e.g. http://unknwon.pgrok.dev). 2. Download the latest version of the pgrok: 1. For Homebrew: brew install pgrok/tap/pgrok 2. For others, download the archive from the Releases page. 3. Initialize a pgrok.yml file with the following command (assuming you want to forward requests to http://localhost:3000): pgrok init --remote-addr pgrok.dev:2222 --forward-addr http://localhost:3000 --token {YOUR_TOKEN} By default, the config file is created under the home directory (~/.pgrok/pgrok.yml). Use --config flag to specify a different path for the config file. 4. Launch the client by executing the pgrok or pgrok http command. 1. By default, pgrok expects the pgrok.yml is available under the home directory (~/.pgrok/pgrok.yml). Use --config flag to specify a different path for the config file. 2. Use the --debug flag to turn on debug logging. 3. Upon successful startup, you should see a log looks like: YYYY-MM-DD 12:34:56 INFO Tunneling connection established remote=pgrok.dev:2222 5. Now visit the URL. Override config options Following config options can be override through CLI flags: * --remote-addr -> remote_addr * --forward-addr -> forward_addr * --token -> token As a special case, the first argument of the pgrok http can be used to specify forward address, e.g. pgrok http 8080 Dynamic forwards In addition to traditional request forwarding to a single address, pgrok can be configured to have dynamic forward rules. For example, if your local frontend is running at http:// localhost:3000 but some gRPC endpoints need talk to the backend directly at http://localhost:8080: dynamic_forwards: | /api http://localhost:8080 /hook http://localhost:8080 Then all request prefixed with the path /api and /hook will be forwarded to http://localhost:8080 and all the rest are forwarded to the forward_addr (http://localhost:3000). Vanilla SSH Because the standard SSH protocol is used for tunneling, you may well just use the vanilla SSH client. 1. Go to http://pgrok.dev, authenticate with your SSO to obtain the token and URL (e.g. http://unknwon.pgrok.dev). 2. Launch the client by executing the ssh -N -R 0::3000 pgrok.dev -p 2222 command: 1. Enter the token as your password. 2. Use the -v flag to turn on debug logging. 3. Upon successful startup, you should see a log looks like: Allocated port 22487 for remote forward to :3000 3. Now visit the URL. Explain it to me pgrok network diagram Sponsors [68747470733a2f2f7777772e62797465626173652] Credits * The logo is from flaticon.com. * The project wouldn't be possible without reading function61/ holepunch-server, function61/holepunch-client, and TCP/IP Port Forwarding. License This project is under the MIT License. See the LICENSE file for the full license text. About Poor man's ngrok - a multi-tenant HTTP reverse tunnel solution through SSH remote port forwarding Topics go http sso reverse-tunnel oidc ssh-tunnel pgrok ngrok-alternative Resources Readme License MIT license Stars 510 stars Watchers 3 watching Forks 11 forks Releases 5 v1.1.1 Latest Mar 11, 2023 + 4 releases Contributors 4 * @unknwon unknwon Joe Chen * @Christoph-Wagner Christoph-Wagner Christoph Wagner * @czyt czyt Chong Zi Ying Tao * @deepsource-io[bot] deepsource-io[bot] Languages * Go 100.0% Footer (c) 2023 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.