Portless

What it does

Portless allows you to replace traditional port numbers in URLs with stable, named .localhost addresses. This simplifies development workflows by eliminating port conflicts, making it easier for both humans and AI agents to access applications. It provides a consistent URL structure regardless of the underlying port being used, preventing issues like stale browser tabs or incorrect configurations when ports change.

When to use it

• Resolving Port Conflicts: When multiple projects attempt to run on the same port (EADDRINUSE errors).
• Simplifying Development Sharing: Easily share URLs with teammates without needing to specify port numbers in communication.
• Managing Monorepos: Streamline development and testing across multiple services within a monorepo.
• AI Agent Interactions: Ensure AI agents consistently access the correct application, avoiding hardcoded or incorrect port assumptions.
• Git Worktrees: Provide unique URLs for each worktree in a Git repository.

Key capabilities

• Replaces port numbers with .localhost URLs.
• Automatic HTTPS proxy startup.
• Supports explicit subdomain routing (e.g., api.myapp.localhost).
• Wildcard subdomain support (--wildcard flag).
• Detects and handles Git worktrees, prepending branch names as subdomains.
• Can be installed globally or as a project dependency.

Example prompts

• "Run my Next.js application using Portless."
• "Start the Portless proxy for my 'myapp' application running next dev."
• "Expose my API service at api.myapp.localhost."

Tips & gotchas

• Installation: It is recommended to install Portless globally (npm install -g portless) or as a project development dependency (npm install -D portless). Avoid using npx for one-off executions.
• Non-Interactive Environments: In CI/CD environments (no TTY, or CI=1), Portless will exit with an error message instead of prompting for input.
• Strict Mode: By default, only explicitly registered subdomains are routed. Use the --wildcard flag to allow any subdomain to fall back to a defined application.