Getting Started

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

- "dev": "next dev"              # http://localhost:3000
+ "dev": "portless myapp next dev"  # http://myapp.localhost:1355

Install

npm install -g portless

Install globally. Do not add as a project dependency or run via npx.

Run your app

portless myapp next dev
# -> http://myapp.localhost:1355

The proxy auto-starts when you run an app. A random port (4000--4999) is assigned via the PORT environment variable. Most frameworks (Next.js, Express, Nuxt, etc.) respect this automatically. For frameworks that ignore PORT (Vite, Astro, React Router, Angular), portless auto-injects --port and --host flags.

Use in package.json

{
  "scripts": {
    "dev": "portless myapp next dev"
  }
}

Subdomains

Organize services with subdomains:

portless api.myapp pnpm start
# -> http://api.myapp.localhost:1355

portless docs.myapp next dev
# -> http://docs.myapp.localhost:1355

Git Worktrees

portless run automatically detects git worktrees. In a linked worktree, the branch name is prepended as a subdomain so each worktree gets its own URL without any config changes:

# Main worktree -- no prefix
portless run next dev   # -> http://myapp.localhost:1355

# Linked worktree on branch "fix-ui"
portless run next dev   # -> http://fix-ui.myapp.localhost:1355

Put portless run in your package.json once and it works everywhere -- the main checkout uses the plain name, each worktree gets a unique subdomain. No collisions, no --force.

How it works

Portless runs a reverse proxy on port 1355. Each app registers a route mapping its hostname to an assigned port. Requests to http://<name>.localhost:1355 are proxied to the app.

Browser (myapp.localhost:1355) -> proxy (port 1355) -> App (random port)

Requirements

• Node.js 20+
• macOS or Linux