portless

Product Introduction

1. Definition: Portless is a developer tool and local HTTPS reverse proxy that replaces ephemeral port numbers with stable, named .localhost URLs for local development. It operates as a system-level service that manages hostname resolution and TLS termination.
2. Core Value Proposition: Portless exists to eliminate the friction of managing changing port numbers and port conflicts in local development environments. It provides developers, teams, and AI agents with consistent, memorable, and production-like HTTPS URLs for all local projects, streamlining the development workflow.

Main Features

1. Stable Named URLs: Portless maps dynamic local server ports to permanent, human-readable hostnames like https://myapp.localhost. It infers the app name from package.json, the git repository, or the directory name, removing the need to remember or communicate port numbers. A portless.json configuration file allows for manual overrides.
2. Automatic HTTPS/HTTP2 Proxy: On first run, Portless automatically generates a local Certificate Authority (CA), prompts the user to trust it, and binds to port 443 (with automatic privilege elevation on macOS/Linux). This creates a local HTTPS environment with valid certificates for all *.localhost domains by default, supporting modern web features that require secure contexts.
3. Intelligent Port Assignment & Framework Detection: The proxy auto-starts and assigns a random port (4000-4999) via the PORT environment variable. For frameworks that ignore PORT (e.g., Vite, Astro, Angular), Portless intelligently injects the correct --port and --host flags into the framework's specific dev server command, ensuring compatibility without manual script modification.
4. Git Worktree Integration: Portless automatically detects Git worktrees. In a linked worktree, the branch name is prepended as a subdomain (e.g., fix-ui.myapp.localhost). This provides unique, collision-free URLs for each feature branch without any configuration changes, ideal for testing multiple versions simultaneously.
5. Configurable Top-Level Domains (TLDs): While .localhost (which resolves automatically) is the default, Portless supports custom TLDs like .test via the --tld flag. It can also use owned domains (e.g., dev.example.com) to mirror production URL structures, which is critical for testing OAuth flows, cross-subdomain cookies, and host-based routing locally.

Problems Solved

1. Pain Point: The instability and memorability problem of localhost port numbers (e.g., localhost:3000, localhost:8080), which change between projects, cause conflicts, and are difficult for AI coding assistants or team documentation to reference reliably.
2. Target Audience: Frontend and full-stack developers using frameworks like Next.js, Nuxt, Vite, and Astro; development teams needing consistent local environments; engineers working with microservices or monorepos; and developers utilizing AI coding agents that interact with local servers.
3. Use Cases: Running multiple local projects simultaneously without port conflicts; sharing local development URLs with team members that remain consistent; testing authentication flows (OAuth, cookies) that require HTTPS and specific hostnames; developing features in parallel Git worktrees with isolated URLs; and providing stable endpoints for AI agents to interact with a local development server.

Unique Advantages

1. Differentiation: Unlike manually editing /etc/hosts or using basic .localhost tricks, Portless provides a fully automated, system-managed proxy with automatic HTTPS. Compared to other local proxy tools, its deep integration with framework dev servers and Git worktrees offers a zero-configuration experience for most common workflows.
2. Key Innovation: The combination of automatic Git worktree-aware subdomain generation and intelligent framework-specific flag injection. This allows developers to use the same package.json script (portless run) across all branches and projects, while the tool handles URL uniqueness and server port configuration transparently, a feature not commonly found in similar utilities.

Frequently Asked Questions (FAQ)

1. How does Portless handle HTTPS and certificates for local development? Portless automatically creates and manages a local Certificate Authority (CA) on your machine. On first run, it guides you to trust this CA. It then generates valid TLS certificates for all your *.localhost domains, enabling HTTPS and HTTP/2 by default without browser security warnings.
2. Can I use Portless with a custom domain like .test or my own domain? Yes. Using the --tld flag (e.g., --tld test), you can configure Portless to use any TLD. For custom owned domains like dev.example.com, Portless will sync the necessary entries to your system's hosts file, allowing you to perfectly mirror your production environment's URL structure locally.
3. What happens to my existing package.json scripts when I use Portless? Your scripts remain clean and unchanged. You run your app by prefixing your normal command with portless (e.g., portless next dev). Portless can also be placed directly inside the package.json script. It intelligently injects required port/host flags for supported frameworks without modifying your original script logic.
4. Does Portless work with Git branches and multiple simultaneous feature branches? Yes, this is a core feature. When you are in a Git worktree (a linked branch checkout), Portless automatically prefixes your app's hostname with the branch name. This means each branch gets a unique, stable URL (e.g., feature-auth.myapp.localhost) without any manual configuration, preventing collisions.
5. Is Portless safe to use? Does it expose my local server to the network? By default, Portless's proxy only listens on the local loopback addresses (127.0.0.1 and ::1). It does not expose your development servers to your local network or the internet unless you explicitly enable LAN mode. It functions entirely within your local machine.