portal-tunnel

Portal - Self-Hostable Relay Tunnel for Localhost

English | 简体中文

Why Portal?

Portal is an open-source tunnel runtime and relay network for publishing services to the agentic web. It exposes local apps, APIs, tools, and agents through self-hosted or public relays, keeps routing and security policy in the local tunnel process, and eliminates the need for hosted vendor accounts or credit cards.

• Self-Hostable & Open Source - Run your own relay with a single command. MIT-licensed with zero telemetry, no enterprise tiers, and no call-home.
• Anonymous Relay Network - Connect to public relays or combine self-hosted and community relays into resilient multi-relay failover pools.
• End-to-End Tenant TLS - For uncached HTTPS stream exposures, TLS terminates in your local tunnel process. Forwarding relays handle ciphertext; relay-held certificate keys remain part of the trust boundary.
• IVNP-backed Overlay Networking - Bridge reverse backhauls over an independent IVNP overlay network when enhanced routing privacy is desired.
• Built-in MITM Detection - The native self-probe compares TLS keying material on a sampled connection; --ban-mitm blocks a relay for that exposure when exporter values differ.
• No Accounts, No API Keys - Authentication uses local secp256k1 cryptographic identities (identity.json) with SIWE challenge signing.
• Native x402 Payments - Route-level micropayments using gasless Sui USDC, Casper wCSPR, or Nano XNO without traditional payment processors.

📖 Explore the Complete Product Capabilities: For the complete matrix of all 20+ supported capabilities across CLI, Agent, SDK, and Relay—including interface support and trust boundaries—see the Canonical Feature Inventory.

Comparison

	Portal	ngrok	Cloudflare Tunnel	frp
Public localhost URL	Yes	Yes	Yes	Yes
Self-hostable	Yes	Enterprise only	No	Yes
Open source	MIT	No	Client only	Apache 2.0
Custom domain	Yes	Paid plans	Yes	Yes
End-to-end tenant TLS	Yes (uncached exposures)	No	No	No
MITM self-probe	Yes (TLS keying material export)	No	No	No
Multi-relay failover	Yes	Managed	Built-in	No
Account required	No	Yes	Yes	No
Native x402 payments	Yes	No	No	No

Quick Start

1. Expose a local service

macOS / Linux:

curl -fsSL https://github.com/gosuda/portal-tunnel/releases/latest/download/install.sh | bash
portal expose 3000

Windows (PowerShell):

$ProgressPreference = 'SilentlyContinue'
irm https://github.com/gosuda/portal-tunnel/releases/latest/download/install.ps1 | iex
portal expose 3000

Portal prints an HTTPS URL when the tunnel is ready. To get a short URL without an Ethereum address, use --name myapp when creating the identity. When that name is available, share https://myapp.<relay-domain>/, printed as short URL in the readiness message (alias_url in JSON logs). The identity-bound URL is also available; it includes the Ethereum address and supports opt-in relay caching. If the name is already taken, Portal prints only the identity-bound URL. An existing identity keeps its saved name; use a new --identity-path to choose a different name. Additional common usages:

# Custom name and explicit relay
portal expose 3000 --name myapp --relays https://portal.example.com --discovery=false

# Mount multiple local services behind one domain
portal expose --name myapp \
  --http-route /api=http://127.0.0.1:3001 \
  --http-route /=http://127.0.0.1:5173

# Dedicated raw TCP port (Minecraft, SSH, databases)
portal expose localhost:25565 --name minecraft --tcp

# Prefer an IVNP overlay backhaul path
portal expose 3000 --overlay

2. Use the local AI agent plugin

The repository includes two plugins for Codex, Claude Code, and Cursor: portal-tunnel (portal-expose and portal-connect) for publishing and reaching services, and portal-relay for running a relay:

# GitHub CLI
gh skill install gosuda/portal-tunnel portal-tunnel/portal-expose

# skills CLI
npx skills add gosuda/portal-tunnel --skill portal-expose

Ask your agent: "Expose my app on port 3000 with Portal and verify the public URL." See plugins/portal-tunnel/README.md and plugins/portal-relay/README.md for full setup instructions.

3. Manage persistent tunnels with Portal Agent

When tunnels should run continuously in the background or as a system service:

portal agent run --config config.toml
portal agent dashboard --config config.toml

See the Portal Agent Guide for configuration syntax and OS service installation.

4. Run your own relay

Deploy an open-source relay in seconds:

git clone https://github.com/gosuda/portal-tunnel
cd portal-tunnel && cp .env.example .env
docker compose up

See Deployment for DNS automation (ACME), TCP/UDP port ranges, and production policy configuration.

How End-to-End Encryption Works

The ordinary uncached forwarding path works as follows:

Browser
  -> Relay SNI router  (reads ClientHello/SNI, forwards tenant ciphertext)
  -> Reverse session
  -> Portal tunnel     (completes TLS handshake locally, derives session keys)
  -> Local service

1. SNI Routing: The relay accepts the incoming connection and reads only the TLS ClientHello for SNI-based lease routing.
2. Raw Forwarding: It forwards the raw encrypted stream over the reverse session without terminating TLS.
3. Local Handshake: The Portal tunnel completes the TLS handshake locally; session keys are derived on your machine.
4. Keyless Signing: For relay-hosted domains, the relay signs handshake transcripts via /v1/sign. The relay never receives session keys.
5. Ciphertext Security: The relay continues forwarding ciphertext without access to tenant plaintext.

Portal minimizes relay trust; it does not yet eliminate it. A malicious relay with the certificate private key can still impersonate an endpoint, and the self-probe checks only sampled connections. See the Security Model for guarantees and exceptions, or Keyless TLS Explained for the design rationale.

Public Relay Registry

Portal includes the official public relay registry by default:

https://raw.githubusercontent.com/gosuda/portal-tunnel/main/registry.json

If you operate a public Portal relay, open a pull request to add your relay URL to registry.json.

Documentation

• Feature Inventory - Canonical inventory of all product capabilities and interfaces.
• Getting Started - Step-by-step setup and first exposure.
• Concepts - Relay and tunnel ownership, transport modes, and overlay networking.
• Security Model - Tenant TLS guarantees, relay signing authority, and cache exceptions.
• Keyless TLS Explained - Technical article on transcript signing, MITM self-probes, and delegation.
• CLI Reference - Complete command-line syntax and flag guide.
• Portal Agent - Multi-tunnel daemon and interactive dashboard.
• Self-Hosting - Running and securing your own relay instances.
• Configuration - Environment variables and configuration options.
• API Reference - Relay wire protocol and client APIs.
• Maintainer Architecture - Internal Go package ownership and data flows.

Contributing

See CONTRIBUTING.md.

License

MIT License - see LICENSE.