Portl is a high-performance, self-hosted reverse tunnel proxy. It allows developers to expose their local development environment to the internet securely, replacing restrictive tools like ngrok with a zero-cost, multi-tenant architecture.
For developers who want to use Portl to tunnel their local projects.
Install the Portl CLI directly from GitHub:
pip install git+https://github.com/KoushalGH/portl.gitAuthorize your client to talk to your Portl server (e.g., your Render deployment):
portl config auth <YOUR_API_KEY> --server your-service-name.onrender.comConnect any local port (e.g., 3000) to a public subdomain:
portl connect 3000 --subdomain my-mobile-appAccess your app at: https://your-service-name.onrender.com/p/my-mobile-app/
- High-Speed Tunneling: Persistent WebSocket-based traffic multiplexing.
- Intelligent Edge Mocking: Serve JSON mocks from the edge when your laptop is offline.
- Traffic Observability: Complete logging of every request/response for debugging.
- Offline Queueing: Incoming webhooks are queued and delivered as soon as you reconnect.
- Chaos Engineering: Built-in mode to inject random 500 errors and latency to test your app's resilience.
- Auto-Discovery: Automatically maps out your API endpoints as you use them.
For administrators who want to host their own Portl infrastructure for free.
Create a new project on Supabase and run the schema found in src/server/schema.sql in the SQL Editor. This sets up the traffic logs and mock tables.
- Fork this repository.
- Create a new Web Service on Render.
- Connect your fork and set the Runtime to
Docker. - Add the following Environment Variables:
SUPABASE_URL: Your project URL.SUPABASE_KEY: Your Service Role Key.PORTL_MASTER_KEY: Your chosen master password for the CLI.
Portl is built with "Secure by Default" principles:
- Anti-SSRF Protection: The client strictly forwards traffic to
127.0.0.1, preventing internal network scanning. - Header Sanitization: Dangerous headers (like
Host) are stripped to prevent host spoofing. - Payload Limits: Rejects any request larger than 50MB to protect local memory.
- Zero-Trust Keys: All tunnel connections require a valid API key verified against your Supabase instance.
| Command | Description |
|---|---|
portl connect <PORT> |
Start a new tunnel |
portl config auth <KEY> |
Set your master authentication key |
portl status |
Check server health and active tunnels |
portl mock add |
Add a new edge mock rule |
portl discover |
Show auto-mapped endpoints |
portl replay <ID> |
Replay a specific logged request |
portl/
├── src/
│ ├── server/ # FastAPI Server & Database Logic
│ └── client/ # Click CLI & WebSocket Tunnel Client
├── tests/ # End-to-End Test Suite
├── Dockerfile # Production-ready Docker Image
└── setup.py # Package configuration
Distributed under the MIT License. See LICENSE for more information.
Built for developers who like full control.