Commands

Run an app

portless run [--name <name>] <cmd> [args...]
portless <name> <cmd> [args...]

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.

portless <name> uses an explicit name with no inference or prefixing.

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
portless docs.myapp next dev

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 skip it.

Alias (static routes)

portless alias <name> <port>
portless alias <name> <port> --force
portless alias --remove <name>

Register a route for a service not managed by portless (e.g. a Docker container). Aliases persist across stale-route cleanup.

portless alias my-postgres 5432     # -> https://my-postgres.localhost
portless alias redis 6379           # -> https://redis.localhost
portless alias --remove my-postgres # remove the alias

List routes

portless list

Shows active routes and their assigned ports.

Trust the CA

portless trust

Adds the portless certificate authority to your system trust store. Required once for HTTPS with auto-generated certs.

Clean up

portless clean

Stops the proxy if it is running, removes the portless CA from the OS trust store when portless installed it, deletes allowlisted files under ~/.portless, the system state directory, and PORTLESS_STATE_DIR when set, and removes the portless block from /etc/hosts. May prompt for elevated privileges. Custom --cert / --key paths are not removed.

Proxy control

Start

portless proxy start

Stop

portless proxy stop

LAN mode

Access services from phones and other devices on the same WiFi via mDNS (.local domains):

portless proxy start --lan
portless proxy start --lan --https
portless proxy start --lan --ip 192.168.1.42   # manual IP override

Make it permanent by adding export PORTLESS_LAN=1 to your shell profile. Portless also remembers LAN mode via proxy.lan, so a stopped LAN proxy starts in LAN mode again unless you override it with PORTLESS_LAN=0 for that start.

Uses dns-sd on macOS (built-in) and avahi-publish-address on Linux (avahi-utils). Not supported on Windows.

Framework notes:

• Next.js: Add allowedDevOrigins: ['myapp.local', '*.myapp.local'] to next.config.js so LAN mode requests still work when portless adds a git worktree prefix.
• Vite / React Router / SvelteKit / Astro: Handled automatically via __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS.
• Expo / React Native: Add NSAllowsLocalNetworking to your app.json for iOS ATS (see Getting Started for the .localhost equivalent using NSExceptionDomains):

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSAppTransportSecurity": {
          "NSAllowsLocalNetworking": true
        }
      }
    }
  }
}

Hosts

portless hosts sync     # add current routes to /etc/hosts
portless hosts clean    # remove portless entries from /etc/hosts

Auto-sync is on by default. Set PORTLESS_SYNC_HOSTS=0 to disable.

Bypass portless

PORTLESS=0 pnpm dev

Runs the command directly without the proxy.

Info

portless --help
portless --version