/portless-local

name: portless-local
description: "Replace port numbers with stable named .localhost URLs for local development"
license: MIT
compatibility: cline, claude, opencode, amp, codex, gemini, cursor, pi
hint: Use when you want clean, named URLs for local development instead of remembering port numbers
user-invocable: true
disable-model-invocation: true
metadata:
  audience: all
  workflow: development
  source: vercel-labs/portless@7abf4df5d939fe3b527a120e20bc270c681c3536
  source_path: skills/portless/SKILL.md

Portless - Named .localhost URLs

Replace port numbers with stable, named `.localhost` URLs for local development. For humans and agents.

> **Note:** The portless CLI enables HTTPS on port 443 by default (`https://myapp.localhost`). Pass `--no-tls` to `portless proxy start`, or set `PORTLESS_HTTPS=0`, for plain HTTP. Keep HTTPS when the app needs OAuth, secure cookies, or HTTP/2.

Safety and Approval

Read existing proxy configuration before starting an app: auto-start reuses saved settings, including LAN mode. Outside LAN mode the proxy binds only to IPv4/IPv6 loopback; LAN mode binds all interfaces.

Ask for explicit approval before first-run sudo/elevation, CA trust-store changes, `/etc/hosts` writes, LAN exposure, Tailscale sharing, public Funnel/ngrok tunnels, startup-service installation/removal, or destructive cleanup. A request for local development does not authorize these actions. Use `PORTLESS_SYNC_HOSTS=0` when hosts writes are not approved. In non-interactive environments, first-run prompts fail rather than granting permission; pre-start only an approved proxy configuration.

`--force` kills the existing process and takes over its route. `prune` terminates orphaned process groups, and `prune --force` uses SIGKILL. Do not use them without checking ownership and approval. `clean` also removes startup services and trust entries; it is not routine project cleanup.

Never print or commit TLS private keys or ngrok tokens. Let the user configure authentication through the provider's private credential workflow. Do not disable TLS verification to resolve proxy errors.

Why Portless?

Local dev with port numbers is fragile. Portless fixes that by giving each dev server a stable, named `.localhost` URL.

| Problem | With Ports | With Portless | | -------------------------- | ------------------------------------------------------- | ----------------------------------------------- | | **Port conflicts** | Two projects on :3000 = EADDRINUSE | Auto-assigned ports, named URLs - no collisions | | **Memorizing ports** | "Was the API on 3001 or 8080?" | Always `https://api.localhost` | | **Wrong app on refresh** | Stop one server, start another on same port = confusion | Named URLs eliminate this | | **Monorepo chaos** | Every service needs a unique port | Distinct hostnames for each service | | **Agent confusion** | AI agents guess/hardcode wrong ports | `https://myapp.localhost` is deterministic | | **Cookie/storage clashes** | Cookies bleed across ports on localhost | Each `.localhost` subdomain gets its own scope | | **Hardcoded config** | CORS, OAuth, .env break when ports change | URLs are stable across restarts | | **Sharing URLs** | "What port is that on?" in Slack | Everyone uses the same named URL | | **Browser history** | `localhost:3000` history is a jumble | Named URLs keep things organized |

Installation

# Global (recommended)
npm install -g portless

# Or as a project dev dependency
npm install -D portless

Requires Node.js 24+ and OpenSSL for certificate generation. Install globally or as a project dependency; do not use a one-off `npx`/`pnpm dlx` download. A local package may be invoked through package scripts or `npx portless` without downloading it.

Usage

Invoke via skill command or use CLI directly:

# Via skill command
/portless-local <NAME> <COMMAND> [OPTIONS]

# Or use CLI directly
portless <NAME> <COMMAND> [OPTIONS]

Commands

Run an App

portless run [--name <name>] <cmd> [args...]   # Infers name from package.json, git root, or directory
portless <name> <cmd> [args...]                # Explicit name, no inference

`portless run` infers the project name from package.json, git root, or directory name. Use `--name` to override the inferred name while still applying worktree prefixes.

| Flag | Description | | --------------------- | --------------------------------------------------------------------------------------------------- | | `--name <name>` | Override the inferred base name (worktree prefix still applies). Only for `portless run`. | | `--app-port <number>` | Use a fixed port for the app instead of auto-assignment. Also configurable via `PORTLESS_APP_PORT`. | | `--force` | Kill the existing process and take over its route; requires ownership checks and approval |

**Examples:**

portless run next dev                    # Infer name from project
portless run --name myapp next dev       # Override inferred name
portless myapp next dev                  # Explicit name
portless api pnpm start                  # API service
portless docs.myapp next dev             # Subdomain

Get a Service URL

portless get <name>

Print the URL for a service. Useful for wiring services together in scripts or env vars:

BACKEND_URL=$(portless get backend)

Applies worktree prefix detection by default. Use `--no-worktree` to