setup-portless - SKILL.md Agent Skill

name: setup-portless description: Sets up Portless for a project to replace port numbers with stable named .localhost URLs. Use when configuring local development routing, fixing port conflicts, or setting up monorepo dev environments.

Set up [Portless](https://github.com/vercel-labs/portless) for the current project. Portless replaces `localhost:PORT` with stable named URLs like `myapp.localhost:1355`, eliminating port conflicts, cookie collisions, and port-guessing issues for both developers and AI agents.

Requirements: Node.js 20+, macOS or Linux.

Run these commands to get started:

# Install globally
npm install -g portless

# Start the proxy daemon
portless proxy start

# Run your app with a named route
portless myapp next dev
# => http://myapp.localhost:1355

Step 1: Verify prerequisites

Check Node.js version is 20+ and platform is macOS or Linux:

node --version
uname -s

If Node.js < 20, inform the user they need to upgrade before proceeding.

Step 2: Detect project context

Read package.json to understand:

Project name (use as default app name)
Existing dev scripts (to know what command to wrap)
Whether this is a monorepo (look for workspaces field, or pnpm-workspace.yaml, turbo.json, lerna.json)
Framework in use (Next.js, Vite, Express, etc.) from dependencies

Step 3: Install Portless

npm install -g portless

Step 4: Choose app name(s)

Ask the user what name they want for their app URL. Suggest based on project name.

For monorepos, suggest subdomain naming:

api.projectname for backend
web.projectname or projectname for frontend
docs.projectname for documentation

Step 5: Update package.json scripts

Wrap the existing dev script with portless. For example, if the current script is:

{ "dev": "next dev" }

Update to:

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

For monorepos, update each workspace's package.json similarly.

Step 6: Verify setup

Run the dev script and confirm the app is accessible at the named URL:

npm run dev

The proxy auto-starts if not already running. Confirm output shows the .localhost:1355 URL.

Verify routes are registered:

portless list

**Single application:**

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

Access at: http://myapp.localhost:1355

**Monorepo with multiple services:**

# In packages/web/package.json
"dev": "portless web.myapp next dev"

# In packages/api/package.json
"dev": "portless api.myapp node server.js"

# In packages/docs/package.json
"dev": "portless docs.myapp next dev"

Access at:

http://web.myapp.localhost:1355
http://api.myapp.localhost:1355
http://docs.myapp.localhost:1355

**Custom proxy port (e.g., port 80 for clean URLs):**

sudo portless proxy start -p 80
# Then: http://myapp.localhost (no port needed)

Variable	Purpose	Default
`PORTLESS=0` or `PORTLESS=skip`	Bypass portless, use default port	(not set)
`PORTLESS_PORT`	Override proxy port	`1355`
`PORTLESS_STATE_DIR`	Custom state directory	`~/.portless` or `/tmp/portless`

Command	Purpose
`portless <name> <cmd> [args...]`	Run app with named route
`portless list`	Show active routes
`portless proxy start`	Start daemon proxy on port 1355
`portless proxy start -p <port>`	Start on custom port
`portless proxy start --foreground`	Run in foreground (debugging)
`portless proxy stop`	Stop the proxy daemon

The proxy auto-starts when you run `portless `, so there is no need to manually start it. Only use `portless proxy start` for custom port configuration. Portless does not support Windows. Only set up on macOS or Linux. Portless requires Node.js 20+. Do not attempt installation on older versions. Setup is complete when: - Portless is installed globally (`portless --version` succeeds) - Project `package.json` dev script(s) are wrapped with `portless ` - Running `npm run dev` (or equivalent) shows the app accessible at `.localhost:1355` - For monorepos, each workspace has its own named route