pgrok: The Self-Hosted Tunneling Tool Every Developer Needs

Tired of paying for ngrok? Worried about exposing your local development environment through third-party servers? You're not alone. Developers everywhere are discovering that relying on external tunneling services creates security blind spots, unexpected costs, and frustrating rate limits. The promise of seamless local development often comes with strings attached.

Enter pgrok – a revolutionary self-hosted alternative that puts you in complete control. This powerful tool transforms your own VPS into a secure tunneling powerhouse, delivering automatic HTTPS, real-time request inspection, and a stunning terminal UI dashboard. No subscriptions. No data passing through unknown servers. Just pure, transparent tunneling that works exactly how you want it.

In this deep dive, we'll explore every facet of pgrok – from its ingenious SSH-based architecture to its color-coded request logging. You'll get step-by-step installation instructions, real code examples extracted directly from the repository, advanced usage patterns, and a complete comparison with commercial alternatives. Whether you're debugging webhooks, demoing prototypes, or building IoT applications, pgrok might just become your most indispensable development tool.

What is pgrok?

pgrok is a personal ngrok alternative created by R44VC0RP that exposes local ports to the internet through your own Virtual Private Server (VPS) with automatic HTTPS encryption. Unlike commercial tunneling services that route your traffic through their infrastructure, pgrok leverages SSH reverse tunnels and Caddy's on-demand TLS to create a completely self-hosted solution.

At its core, pgrok combines three powerful technologies into one elegant package:

1. SSH Reverse Tunneling – Establishes secure, encrypted connections from your local machine to your VPS without exposing additional ports
2. Caddy Server – Provides automatic HTTPS certificates via Let's Encrypt and ZeroSSL with zero configuration
3. Interactive TUI Dashboard – Built with OpenTUI, delivers real-time connection stats, request logs, and TLS provisioning status in your terminal

The tool is specifically designed for single-user, personal use – making it perfect for individual developers, freelancers, and small teams who need reliable tunneling without enterprise complexity. It's trending in developer communities because it solves the classic ngrok pain points: monthly fees, connection limits, and the security implications of routing sensitive development data through third-party servers.

What makes pgrok truly special is its transparent architecture. Every component is visible and controllable. You can inspect the Python scripts that manage Caddy routes, modify the Caddyfile for custom behavior, and even hack on the TUI client itself. This isn't a black-box service – it's a toolkit you own completely.

Key Features That Make pgrok Stand Out

SSH-Native Tunneling Architecture

pgrok's foundation is pure SSH – no proprietary protocols, no extra binaries on the server. When you run pgrok myapp 4000, the client establishes a standard SSH reverse tunnel using the -R flag. This means no firewall configuration, no port forwarding, and no additional attack surface on your VPS. The tunnel binds to localhost only (GatewayPorts no), ensuring that only Caddy can proxy traffic through it, not external attackers.

Automatic HTTPS with Dual Certificate Providers

Caddy's on-demand TLS system is the secret sauce. When a request hits myapp.yourdomain.com, Caddy instantly provisions a certificate through Let's Encrypt. Hit rate limits? No problem – pgrok automatically falls back to ZeroSSL. The pgrok-ask validation script ensures only single-level subdomains of your configured domain can request certificates, preventing abuse. Certificates are cached and auto-renewed without manual intervention.

Real-Time TUI Dashboard with OpenTUI

Forget boring console output. pgrok's terminal UI, powered by OpenTUI, transforms your tunneling experience into a visual delight. The dashboard displays:

• Session Status – Visual indicators for connecting, provisioning TLS, online, and error states
• Connection Metrics – Live request counts, open connections, and rate tracking (1m/5m windows)
• Response Analytics – p50 and p90 latency percentiles to spot performance issues
• Color-Coded HTTP Logs – Instantly identify methods (GET=blue, POST=purple) and status codes (2xx=green, 5xx=red)

Intelligent Request Inspection

Every HTTP request flowing through your tunnel is logged with precision. The system captures method, path, status code, and duration, then color-codes them for instant visual parsing. Slow endpoints (>500ms) appear in red, warning you immediately. This turns pgrok into a miniature APM tool for your local development.

Zero-Configuration Wildcard Domains

Once you set up a wildcard DNS record (*.yourdomain.com), pgrok creates new subdomains instantly. No DNS changes, no waiting for propagation. Run pgrok api 3000 and https://api.yourdomain.com is live within seconds. This ephemeral subdomain pattern is perfect for feature branch previews and client demos.

Security-First Design

The server setup creates a dedicated pgrok user with restricted SSH permissions – only remote forwarding allowed. The Caddy admin API listens on localhost only, and the pgrok-ask service acts as a gatekeeper for certificate requests. SSH key authentication is mandatory; passwords are explicitly disabled.

Real-World Use Cases Where pgrok Shines

1. Webhook Development and Debugging

Building a Stripe integration? Testing GitHub webhooks? pgrok is your best friend. Instead of configuring ngrok and hoping its free tier doesn't throttle you, spin up pgrok stripe 4242 and get a permanent, memorable URL like https://stripe.yourdomain.com. The TUI dashboard shows every incoming webhook in real-time, letting you inspect headers, verify signatures, and debug payload issues instantly. The color-coded logs make it trivial to spot 4xx errors from malformed requests.

2. Mobile Application Backend Testing

Testing a React Native or Flutter app against your local API server is painful without tunneling. pgrok solves this elegantly: pgrok mobile-api 3000 creates https://mobile-api.yourdomain.com that your physical device can reach. Because you control the domain, you can add it to your app's allowlist once and never worry about random ngrok URLs again. The connection stats help you identify mobile network latency issues versus actual server problems.

3. Client Demos Without Deployment

Need to show a work-in-progress feature to a client? pgrok demo-feature 5173 (assuming Vite on port 5173) generates a professional-looking URL that doesn't scream "temporary tunnel." Your clients see https://demo-feature.yourdomain.com – clean, branded, and trustworthy. When the demo ends, Ctrl+C cleans up everything automatically. No stale tunnels, no forgotten processes.

4. IoT Device Remote Administration

Managing Raspberry Pi devices or custom hardware in the field? pgrok can expose administrative interfaces securely. Run pgrok iot-admin 8080 on the device to access its control panel from anywhere. Since SSH is the transport layer, you get strong encryption by default. The restricted pgrok user and localhost-only binding mean even if the device is compromised, attackers can't pivot through the tunnel.

5. Database Administration and Monitoring

Expose your local PostgreSQL or Redis admin interface safely: pgrok pgadmin 5050. The HTTPS termination happens at Caddy, but the tunnel itself is encrypted end-to-end via SSH. You can monitor who's connecting, when, and what they're doing through the request logs. For extra security, combine with IP whitelisting in Caddy to restrict access to your office IP.

Step-by-Step Installation & Setup Guide

Prerequisites Checklist

Before starting, ensure you have:

• A VPS with a public IP address (DigitalOcean, Linode, AWS Lightsail, etc.) with ports 80 and 443 open and unused
• Docker and Docker Compose installed on the VPS
• A domain name you control (e.g., yourdomain.com)
• An SSH key on your local machine (generate with ssh-keygen -t ed25519 if needed)

Step 1: Configure Wildcard DNS

Log into your DNS provider (Cloudflare, Vercel, Namecheap, etc.) and add a wildcard A record:

Critical: If using Cloudflare, disable the orange proxy cloud – Caddy needs direct access for HTTP-01 challenges.

Step 2: Install the pgrok Client

On your local Mac or Linux machine, run:

curl -fsSL https://raw.githubusercontent.com/R44VC0RP/pgrok/main/install.sh | bash -s client

The interactive installer will:

• Auto-detect your SSH key (~/.ssh/id_ed25519 or ~/.ssh/id_rsa)
• Build the pgrok binary from source
• Prompt for your VPS IP, domain, and email
• Copy a server setup command to your clipboard (with your SSH key embedded)

Step 3: Configure the VPS Server

SSH into your VPS and paste the command from Step 2. Alternatively, run:

curl -fsSL https://raw.githubusercontent.com/R44VC0RP/pgrok/main/install.sh | sudo bash -s server

This script performs server-side magic:

• Installs Caddy via Docker Compose
• Creates a restricted pgrok user
• Adds your SSH key to /home/pgrok/.ssh/authorized_keys
• Configures SSH daemon for secure tunneling
• Starts the pgrok-ask validation service
• Launches Caddy with on-demand TLS

Step 4: Verify Installation

On your local machine, test the setup:

pgrok test 8000

You should see the TUI dashboard launch and display "Session Status: online" within 10-20 seconds. Visit https://test.yourdomain.com in your browser – if you see your local server, everything works!

Step 5: Rebuild After Updates

When updating pgrok, rebuild the binary:

./setup.sh client --rebuild

This ensures you have the latest TUI improvements and bug fixes.

Real Code Examples from the Repository

Example 1: Basic Tunnel Creation

The simplest pgrok usage exposes a local development server:

# Expose your React/Vite/Next.js dev server
pgrok myapp 4000
# => https://myapp.yourdomain.com -> localhost:4000

What happens under the hood:

• The client reads your ~/.pgrok/config file for VPS credentials
• Establishes SSH connection to pgrok@your-vps-ip
• Creates reverse tunnel: -R 127.0.0.1:PORT:localhost:4000
• Sends subdomain "myapp" to the server's pgrok-tunnel script
• The script dynamically updates Caddy's config to proxy myapp.yourdomain.com to the tunnel endpoint
• Caddy triggers certificate provisioning via Let's Encrypt
• The TUI dashboard displays real-time status and logs

Example 2: Exposing an API with Debug Logging

For debugging webhook issues or API integrations:

# Expose local API with detailed tunnel logs
pgrok api 3000 --print-logs

The --print-logs flag is a game-changer for troubleshooting. When you press Ctrl+C to stop the tunnel, pgrok dumps the raw SSH tunnel logs to /tmp/pgrok-debug.log. This reveals:

• SSH connection handshake details
• Port binding successes/failures
• TLS provisioning errors
• Caddy configuration updates

Example 3: Configuration File Structure

After installation, your client config lives at ~/.pgrok/config:

# ~/.pgrok/config - Client configuration
PGROK_HOST=203.0.113.42          # Your VPS IP address
PGROK_DOMAIN=yourdomain.com      # Your wildcard domain
PGROK_USER=pgrok                 # Restricted SSH user
PGROK_SSH_KEY=~/.ssh/id_ed25519  # Path to your SSH private key

Key configuration insights:

• PGROK_HOST must be a raw IP address, not a domain (prevents DNS lookup issues)
• PGROK_DOMAIN should be the root domain, not a subdomain
• The SSH key must have 600 permissions (chmod 600 ~/.ssh/id_ed25519)
• You can override these with environment variables for multi-VPS setups

Example 4: Server-Side Caddyfile Configuration

The server's /opt/pgrok/Caddyfile demonstrates on-demand TLS:

# /opt/pgrok/Caddyfile - On-demand TLS configuration
{
    # Auto HTTPS with Let's Encrypt and ZeroSSL fallback
    on_demand_tls {
        ask http://localhost:3555/should-provision-cert
    }
}

# Wildcard catch-all for subdomains
*.yourdomain.com {
    tls {
        on_demand
    }
    
    # Proxy to SSH tunnel endpoint
    reverse_proxy localhost:{backend_port}
}

How this works:

• on_demand_tls asks the pgrok-ask service (port 3555) if it should provision a cert
• The Python script validates the subdomain is single-level (e.g., api but not api.v2)
• Caddy attempts Let's Encrypt first, falling back to ZeroSSL automatically
• The reverse_proxy directive forwards traffic to the dynamic SSH tunnel port

Example 5: Development Mode Commands

For contributors hacking on the TUI:

cd client/tui
bun install                    # Install dependencies
bun run index.ts myapp 4000    # Run in development mode with hot reload
bun run build                  # Compile to standalone binary
bun run tsc --noEmit           # Type-check without building

Development workflow:

• The TUI is built with TypeScript and OpenTUI framework
• bun provides fast iteration cycles
• The compiled binary is a single, portable executable
• Type-checking ensures dashboard components stay in sync

Advanced Usage & Best Practices

Running Multiple Tunnels Simultaneously

pgrok supports concurrent tunnels by running multiple instances. Use terminal panes or tmux:

# Terminal 1: Frontend
pgrok frontend 5173

# Terminal 2: Backend API
pgrok backend 3000

# Terminal 3: WebSocket service
pgrok ws 8080

Pro tip: Create shell aliases for frequent projects:

alias pgrok-app="pgrok myapp 4000"
alias pgrok-api="pgrok api 3000"

Custom Domain Patterns

While pgrok uses subdomains by default, you can modify the server script for path-based routing. Edit /usr/local/bin/pgrok-tunnel to support patterns like yourdomain.com/app1 → localhost:4000.

Monitoring and Alerting

Pipe the TUI output to a log file for persistent monitoring:

pgrok critical-service 5000 2>&1 | tee tunnel.log

Set up cron jobs to check tunnel health:

# Check if tunnel is responsive every 5 minutes
*/5 * * * * curl -f https://api.yourdomain.com/health || systemctl restart pgrok-client

Security Hardening

1. IP Whitelisting: Modify the Caddyfile to restrict access:

@trusted remote_ip 203.0.113.0/24
reverse_proxy @trusted localhost:{backend_port}

2. Rate Limiting: Add Caddy's rate limit module to prevent abuse
3. SSH Hardening: Use Match User pgrok in sshd_config to restrict the pgrok user to forwarding only

CI/CD Integration

Use pgrok in GitHub Actions for preview deployments:

- name: Start tunnel
  run: |
    pgrok pr-${{ github.event.number }} 3000 &
    echo "Preview: https://pr-${{ github.event.number }}.yourdomain.com"

Comparison with Alternatives

Why pgrok wins for personal use:

• No subscription fatigue: Pay once for a $5/month VPS, use forever
• No rate limits: Let's Encrypt allows 50 certs/week per domain – plenty for individual use
• Complete transparency: Every packet's path is visible and auditable
• Professional URLs: client-demo.yourdomain.com looks more trustworthy than random ngrok URLs
• Learning opportunity: Understanding the SSH + Caddy + Python stack makes you a better DevOps engineer

Frequently Asked Questions

Q: How is pgrok different from running SSH tunnels manually? A: Manual SSH tunnels require configuring a reverse proxy, managing TLS certificates, and writing scripts for dynamic routing. pgrok automates all of this with a single command, adds request logging, and provides a beautiful dashboard. It's the difference between building a car from parts and turning a key.

Q: Is pgrok production-ready? A: pgrok is designed for development and staging environments, not production traffic. It handles single-user workloads excellently but lacks multi-tenancy, automatic failover, and advanced load balancing. For production, consider Cloudflare Tunnel or a full Kubernetes ingress setup.

Q: Can I use pgrok on Windows? A: Currently, pgrok supports Mac and Linux only. The installer and TUI client rely on Unix-specific features. Windows users can run it in WSL2, though native support would require community contributions. The repository welcomes PRs for Windows compatibility!

Q: What happens if I hit Let's Encrypt rate limits? A: pgrok automatically falls back to ZeroSSL when Let's Encrypt returns a rate limit error. The TUI dashboard shows "Provisioning TLS..." during this process. With 50 certificates per week per domain, individual developers rarely hit limits unless creating excessive subdomains.

Q: How secure is pgrok compared to ngrok? A: More secure for privacy-conscious developers. Your traffic never leaves your control – it goes from your machine → your VPS → your machine. ngrok routes through their infrastructure. pgrok uses SSH key auth only, restricted users, and localhost-only tunnel binding. However, you're responsible for VPS security hardening.

Q: Can I expose non-HTTP services like databases? A: pgrok is HTTP/HTTPS only by design. The Caddy + SSH tunnel architecture expects HTTP traffic. For databases, use traditional SSH port forwarding or WireGuard. For WebSockets, pgrok passes them through but doesn't log the frames.

Q: What if my connection drops? A: pgrok does not auto-reconnect (by design, to prevent zombie processes). You'll need to restart the command. For persistent tunnels, wrap pgrok in a systemd service or use a process manager like PM2 with restart policies.

Conclusion: Take Control of Your Development Tunneling

pgrok represents a paradigm shift in how developers think about local development exposure. It proves that with modern tools like Caddy and OpenTUI, we can build solutions that rival commercial offerings while maintaining complete ownership. The combination of SSH's ubiquity, Let's Encrypt's free certificates, and a thoughtfully crafted TUI creates an experience that's both powerful and delightful.

The real magic isn't just the technology – it's the philosophy. pgrok treats developers as capable engineers who can manage their own infrastructure, not as consumers locked into SaaS platforms. Every line of code is inspectable, every configuration tweakable, every log readable.

If you're spending $20/month on ngrok Pro, or hitting rate limits during critical debugging sessions, pgrok is your escape hatch. For the cost of a $5 VPS and 15 minutes of setup, you get unlimited tunnels, professional domains, and a dashboard that makes you feel like a DevOps wizard.

Ready to liberate your tunnels? Head to the pgrok GitHub repository, star it for later reference, and follow the Quick Start guide. Your future self – debugging webhooks at 2 AM with full request visibility – will thank you.

The era of renting tunnels is over. Long live self-hosted simplicity.