
Setup Portless
Configure Portless for stable localhost URLs in development
What You Can Do
This skill detects your project structure, installs Portless globally, and configures your dev scripts to use stable named URLs instead of port numbers. It handles monorepo detection, suggests appropriate subdomain naming conventions, and updates your package.json automatically—saving you from manual configuration and port conflict headaches.
Features
checks Node.js 20+ and macOS/Linux compatibility before proceeding
reads package.json to identify framework, dev scripts, and monorepo structure (Turbo, Lerna, pnpm workspaces)
installs or verifies the Portless proxy daemon
suggests subdomain names based on project type and monorepo workspace structure
updates package.json scripts to wrap existing commands with portless routing
generates naming schemes for multi-package setups (api.projectname, web.projectname, etc.)
provides commands to start and manage the Portless proxy service
Example Output
Example 1: Single Next.js project
✓ Node.js 20.1.0 detected
✓ Platform: macOS (compatible)
✓ Project: my-app (Next.js)
✓ Portless installed globally
Suggested app name: my-app
Updated dev script: portless my-app next dev
=> URL: http://my-app.localhost:1355
Example 2: Monorepo (Turbo)
✓ Turbo monorepo detected (3 workspaces)
✓ Portless installed globally
Workspace routing plan:
- apps/web → portless web turbo dev
- apps/api → portless api turbo dev
- packages/docs → portless docs turbo dev
Updated root dev scripts for coordinated startup
What's Included
- setup-portless.md: the core instruction file with detection logic and configuration workflow
- Portless installation checklist: prerequisite verification steps and platform compatibility guide
- Package.json script templates: ready-to-use wrapped dev commands for single projects and monorepos
- Monorepo configuration framework: subdomain naming conventions and multi-workspace setup patterns
- Proxy daemon quick-start reference: commands to initialize and manage the Portless service
Who It's For
- Full-stack developers — streamline local dev environment routing across multiple services
- Monorepo maintainers — coordinate stable URLs across workspaces without port conflicts
- DevOps engineers — standardize naming conventions for development proxying across teams
- Next.js and Vite developers — eliminate port reassignment friction during development
- AI-assisted development — enable stable URL references for Claude and other AI agents in local testing
Best For
- Setting up new project dev environments with stable naming from the start
- Migrating existing projects from port-based localhost to named URL routing
- Configuring monorepo dev scripts across multiple workspaces simultaneously
- Resolving port conflicts in complex development setups with many services
- Establishing team-wide conventions for local development URL naming







