amalshaji/portr

Portr is a tunnel solution that allows you to expose local HTTP, TCP, or WebSocket services to the public internet. Servers can run either SSH or WebSocket as the client-to-server tunnel transport, and generated client configs tell the client which transport to use.

Portr is primarily designed for small teams looking to expose development servers on a public URL. It is not recommended for use alongside production servers.

Features

• 🎉 Expose local HTTP, TCP, and WebSocket services on public URLs.
• 🚨 Built-in local inspector on http://localhost:7777 for request inspection, replay, and WebSocket session debugging. Watch video.
• 🤖 Agent-friendly local request logs with portr logs, backed by ~/.portr/db.sqlite.
• 👾 Admin dashboard for team, user, and connection management. Watch video.

Quick Start

1. Set up a Portr server or use an existing one.
2. Install the Portr client on your machine.
3. Start a local service, then expose it:

portr http 9000

To pin the tunnel to a subdomain:

portr http 9000 -s amal-test
# or
portr http 9000 --subdomain amal-test

Starting an HTTP tunnel does three useful things immediately:

• Creates a public HTTPS URL that forwards to your local service.
• Starts the Portr inspector locally at http://localhost:7777.
• Persists HTTP request logs locally so they can be queried from the CLI.

HTTP tunnels also support WebSocket upgrades, so a local WebSocket endpoint behind the tunneled HTTP service can be reached with wss://<subdomain>.<server-domain>. HTTP tunnels start two tunnel workers by default; set pool_size in the client config when you need a different worker count.

Inspector And Logs

The local inspector lets you:

• inspect incoming HTTP requests and responses
• replay stored requests as-is or edit method, path, headers, and body before replaying
• inspect headers and payloads
• monitor upgraded WebSocket sessions and captured frames

The same stored request data is available from the CLI:

# Show the latest logs for a subdomain
portr logs amal-test

# Filter by URL substring
portr logs amal-test /api/

# Emit the full stored records as JSON
portr logs amal-test --json

Setup

Deploy the server on Railway with one click (see the Railway guide):

• Server setup guide
• Client installation guide
• HTTP tunnel guide
• Getting started guide

Agent Skills

This repo includes a portr-cli skill for Claude Code and Codex through Vercel Labs skills.

Install it into both agents from GitHub:

npx skills add amalshaji/portr --skill portr-cli -a claude-code -a codex -y

To install it globally instead:

npx skills add amalshaji/portr --skill portr-cli -a claude-code -a codex -g -y

Contributing

Please read through our contributing guide and set up your development environment.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for the full license text.