Getting Started

Get up and running with Porthole in minutes. This guide covers installation and your first tunnel.

Installation

Run instantly with npx (no install):

npx @porthole.dev/cli 8080

Or install the CLI globally with npm:

npm install -g @porthole.dev/cli

Creating Your First Tunnel

Once installed, you can expose a local port with a single command:

porthole 8080

This will generate a public URL that forwards traffic to your local service running on port 8080.

Custom Subdomains

By default, Porthole uses your git repository or folder name as the subdomain. If that name is already in use, it automatically retries with a short random suffix.

To request a specific subdomain:

porthole 8080 --name demo-api

If demo-api is taken, the CLI will fall back to demo-api-<random> automatically.

Command Reference

Basic Usage

• porthole <port>: Expose a local HTTP/HTTPS service.
• porthole list: List active tunnels (preview).
• porthole stop <tunnel-id>: Stop a running tunnel (preview).

Configuration

Porthole works out of the box with sensible defaults, but you can customize your experience using environment variables.

• PORTHOLE_RELAY_HOST: Override the relay WebSocket host (e.g. localhost:8787).
• PORTHOLE_TUNNEL_DOMAIN: Override the public tunnel domain.