portless
Set up and use portless for named local dev server URLs (e.g. https://myapp.localhost instead of http://localhost:3000). Use when integrating portless into a project, configuring dev server names, setting up the local proxy, working with .localhost domains, or troubleshooting port/proxy issues.
Security Assessment
Detected risks:
About portless
Portless is a developer utility that replaces traditional port-based localhost URLs with stable, human-readable .localhost addresses. By eliminating the need to remember specific port numbers, it resolves common issues like port conflicts, stale browser tabs showing the wrong app, cookie and localStorage clashes, and misconfigured environment variables. This allows developers and automated agents to interact with local applications reliably without the overhead of tracking ports across multiple projects or monorepo structures.
The main features of Portless include global or per-project installation, automatic HTTPS proxy startup on port 443, and optional configuration through a portless.json file. It supports zero-configuration usage by inferring app names from package names, git roots, or directories. In monorepos, it can manage multiple packages, automatically discovering them via workspace definitions and providing optional hostname overrides. Portless ensures predictable local development URLs, even in CI environments, and allows explicit environment variable overrides to maintain consistent proxy behavior.
Portless is ideal for web developers working on single projects, multi-service monorepos, or CI pipelines where reliable local URLs are critical. It benefits teams collaborating on projects by providing sharable, named URLs that prevent port-related issues. Use cases include running local development servers without port conflicts, integrating with task runners like Turborepo, managing multiple apps in a monorepo, and simplifying local proxy setup for OAuth redirects, CORS allowlists, and debugging scenarios.
FAQ
How do I install Portless?
You can install Portless globally using 'npm install -g portless' or as a project dev dependency with 'npm install -D portless'. Avoid using npx or pnpm dlx for one-off execution.
Can Portless handle multiple apps in a monorepo?
Yes, Portless can manage multiple packages in a monorepo by using a single portless.json at the repo root. It discovers packages from pnpm-workspace.yaml or the 'workspaces' field in package.json, allowing optional name overrides.
What happens if the proxy is not running in CI or non-interactive environments?
Portless exits with a descriptive error instead of prompting. In these environments, task runners should pre-start the proxy to ensure local URLs are available.
How does Portless determine app names for zero-config setups?
It infers the app name from the package name, git root, or directory. You can override the name using a portless.json file if desired.
Can I specify a different script instead of the default 'dev'?
Yes, you can run a different script using the '--script' option, for example 'portless --script start', or define it in the portless.json configuration.
Install portless
Quick Setup:
- Copy the skill folder to
.claude/skills/ - Claude will automatically detect and use the skill
Repository
vercel-labs/portless