Portless - stabilne adresy localhost bez numerów portów

Portless - koniec z żonglowaniem portami w local development

Port 3000 jest zajęty. Port 3001 też. Który to był ten backend?

Lokalny development w 2026 roku wygląda mniej więcej tak: frontend na porcie 3000, backend API na 4000, dokumentacja na 3001, panel admina na 3002. Uruchamiasz piąty serwis i dostajesz EADDRINUSE - port zajęty. Zmieniasz na 3005. Dzień później nie pamiętasz, który projekt działa na którym porcie. Otwierasz zakładkę z localhost:3000, ale tam jest już zupełnie inna aplikacja niż wczoraj. Ciasteczka i localStorage z poprzedniego projektu mieszają się z aktualnym.

Jeśli to brzmi znajomo, Portless rozwiązuje dokładnie ten problem.

Czym jest Portless?

Portless to narzędzie stworzone przez Vercel Labs, które zastępuje tradycyjne adresy localhost:PORT czytelnymi, stabilnymi nazwami w formacie nazwaaplikacji.localhost:1355. Zamiast pamiętać, że frontend działa na porcie 3000, a API na 4000, po prostu otwierasz myapp.localhost:1355 i api.myapp.localhost:1355.

Pod spodem Portless uruchamia reverse proxy na porcie 1355, który kieruje ruch do odpowiednich aplikacji. Każda aplikacja dostaje losowy port z zakresu 4000-4999 przez zmienną środowiskową PORT, a proxy mapuje nazwy na porty. Ty nigdy nie musisz znać tych portów - pracujesz wyłącznie z nazwami.

Dlaczego Portless?

Problemy z tradycyjnym podejściem

Numery portów to techniczny detal, który nie powinien zajmować przestrzeni mentalnej programisty. A jednak:

• Konflikty portów - EADDRINUSE to jeden z najczęściej spotykanych błędów w development. Dwa projekty domyślnie chcą tego samego portu i trzeba ręcznie rozwiązywać konflikt.
• Pamięć - w monorepo z pięcioma serwisami musisz pamiętać pięć numerów portów. Po tygodniu przerwy od projektu - powodzenia.
• Ciasteczka i localStorage - przeglądarka przypisuje je do hosta. Gdy na localhost:3000 uruchomisz dziś inny projekt niż wczoraj, odziedziczy on ciasteczka poprzedniego.
• Konfiguracja CORS i OAuth - allowlisty, redirect URI, pliki .env - wszystko opiera się na konkretnych portach. Zmiana portu oznacza łańcuch zmian w konfiguracji.
• Komunikacja w zespole - "uruchom backend na 4000" - ale co jeśli kolega ma tam inny projekt?
• Agenci AI - narzędzia jak Cursor, Claude Code czy Copilot zgadują porty lub hardcodują domyślne wartości. W monorepo to przepis na problemy.

Co daje Portless

Jak to działa?

Architektura Portless opiera się na trzech elementach:

Przeglądarka                  Proxy                    Aplikacja
myapp.localhost:1355  →  port 1355 (daemon)  →  port 4123 (next dev)
api.myapp.localhost:1355  →  port 1355 (daemon)  →  port 4567 (express)

1. Proxy daemon nasłuchuje na porcie 1355 (lub innym skonfigurowanym)
2. Wrapper portless uruchamia aplikację z losowym portem przypisanym do zmiennej PORT
3. Proxy rejestruje trasę - mapuje nazwę hosta na przydzielony port
4. Przeglądarka łączy się z nazwa.localhost:1355, proxy przekierowuje do właściwego portu

Większość frameworków (Next.js, Vite, Express, Nuxt, Remix) automatycznie respektuje zmienną PORT, więc nie trzeba niczego zmieniać w konfiguracji projektu.

Instalacja

Wymagania

• Node.js 20 lub nowszy
• macOS lub Linux

Instalacja globalna

npm install -g portless

Szybki start

portless myapp next dev

To polecenie robi trzy rzeczy naraz:

• Uruchamia proxy daemon (jeśli jeszcze nie działa)
• Przydziela losowy port i ustawia zmienną PORT
• Rejestruje trasę myapp.localhost:1355

Otwórz http://myapp.localhost:1355 w przeglądarce i gotowe.

Polecenia CLI

Uruchamianie aplikacji

Podstawowy wzorzec to portless <nazwa> <polecenie>:

portless myapp next dev

Aplikacja dostępna pod http://myapp.localhost:1355.

portless api.myapp pnpm start

Subdomena - dostępna pod http://api.myapp.localhost:1355.

portless docs.myapp next dev

Kolejna subdomena - http://docs.myapp.localhost:1355.

Zarządzanie proxy

portless proxy start

Uruchamia daemon proxy w tle. Zwykle nie musisz tego robić ręcznie, bo proxy auto-startuje przy pierwszym uruchomieniu aplikacji.

portless proxy stop

Zatrzymuje daemon proxy.

portless proxy start --foreground

Uruchamia proxy na pierwszym planie - przydatne do debugowania, bo logi trafiają bezpośrednio do terminala.

Listowanie tras

portless list

Wyświetla aktywne trasy - które nazwy są zmapowane na które porty.

Integracja z package.json

Zamiast uruchamiać portless ręcznie, dodaj go do skryptów projektu:

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

Teraz pnpm dev automatycznie uruchomi proxy i przydzieli stabilną nazwę. Każdy członek zespołu używa tego samego adresu myapp.localhost:1355.

Monorepo z wieloma serwisami

{
  "packages": {
    "web": {
      "scripts": {
        "dev": "portless web.myapp next dev"
      }
    },
    "api": {
      "scripts": {
        "dev": "portless api.myapp node server.js"
      }
    },
    "docs": {
      "scripts": {
        "dev": "portless docs.myapp next dev"
      }
    }
  }
}

Trzy serwisy, trzy czytelne adresy:

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

HTTPS i HTTP/2

Włączenie HTTPS

portless proxy start --https

Portless generuje lokalne certyfikaty TLS i uruchamia proxy z obsługą HTTP/2. Adresy zmieniają się na https://myapp.localhost:1355.

Zaufanie do certyfikatu

Przeglądarka wyświetli ostrzeżenie o niezaufanym certyfikacie. Żeby tego uniknąć:

sudo portless trust

To polecenie dodaje lokalny CA (Certificate Authority) do systemowego magazynu zaufanych certyfikatów. Wystarczy uruchomić raz.

Własne certyfikaty

Jeśli masz własne certyfikaty (np. od mkcert):

portless proxy start --cert ./cert.pem --key ./key.pem

Dlaczego HTTP/2 ma znaczenie w development?

Przeglądarki ograniczają HTTP/1.1 do 6 równoczesnych połączeń na hosta. Dev servery, które serwują wiele niezbudowanych plików (Vite, Nuxt w trybie dev), mogą przez to ładować się wolniej. HTTP/2 multipleksuje wszystkie żądania na jednym połączeniu, eliminując to ograniczenie.

Trwałe włączenie HTTPS

Zamiast dodawać flagę --https za każdym razem:

export PORTLESS_HTTPS=1

Dodaj to do .bashrc lub .zshrc, żeby HTTPS był domyślnie włączony.

Zmienne środowiskowe

Portless można konfigurować przez zmienne środowiskowe:

Wyłączanie Portless dla pojedynczego polecenia

Czasem chcesz uruchomić aplikację bezpośrednio, bez proxy:

PORTLESS=0 portless myapp next dev

Aplikacja uruchomi się na swoim domyślnym porcie, z pominięciem proxy.

Niestandardowy port proxy

Domyślny port 1355 nie wymaga sudo. Jeśli chcesz użyć portu poniżej 1024 (np. 80 lub 443):

sudo portless proxy start -p 443 --https

Wtedy adresy wyglądają tak: https://myapp.localhost - bez numeru portu w URL.

Katalog stanu

Portless przechowuje trasy, pliki PID i informacje o portach:

• Porty < 1024 (wymaga sudo): /tmp/portless (współdzielony między root a użytkownikiem)
• Porty >= 1024: ~/.portless (scope użytkownika)

Kompatybilność z frameworkami

Portless działa z każdym frameworkiem, który respektuje zmienną środowiskową PORT. W praktyce obejmuje to zdecydowaną większość popularnych narzędzi:

Jeśli Twój framework wymaga ręcznego ustawienia portu, upewnij się, że czyta go z process.env.PORT.

Portless a agenci AI

Jednym z mniej oczywistych zastosowań Portless jest praca z agentami kodującymi. Narzędzia jak Cursor, Claude Code, Copilot czy Codex często muszą wiedzieć, pod jakim adresem działa aplikacja - na przykład żeby otworzyć preview, przetestować endpoint API czy zweryfikować, że zmiana działa.

Problem w tym, że agenci nie mają pewności, na którym porcie działa serwer. W monorepo sytuacja jest jeszcze gorsza - pięć serwisów na pięciu portach, a agent widzi tylko output konsoli.

Z Portless nazwy są stałe i przewidywalne. Agent wie, że frontend to zawsze myapp.localhost:1355, a API to api.myapp.localhost:1355. Bez zgadywania.

Porównanie z alternatywami

Portless nie zastępuje Caddy czy nginx w produkcji. Jest narzędziem stricte deweloperskim, zoptymalizowanym pod szybki start i zerową konfigurację.

Praktyczne scenariusze

Projekt solowy z frontendem i backendem

portless web next dev
portless api node server.js

Dwa polecenia, dwa stabilne adresy. Żadnych plików konfiguracyjnych.

Monorepo z Turborepo

W turbo.json definiujesz zadania dev, a w package.json każdego pakietu używasz Portless:

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

turbo dev uruchomi wszystkie serwisy równolegle, każdy z własnym adresem .localhost.

Praca zespołowa

Cały zespół instaluje Portless globalnie i używa tych samych nazw w skryptach package.json. Nie trzeba synchronizować portów, edytować /etc/hosts ani aktualizować dokumentacji. Adres myapp.localhost:1355 jest taki sam na każdej maszynie.

Testowanie webhooków

Jeśli testujesz webhooki z HTTPS, Portless z flagą --https daje Ci lokalny certyfikat TLS bez konieczności konfigurowania ngrok czy Cloudflare Tunnel do podstawowych testów.

Najczęściej zadawane pytania

Czy Portless działa na Windowsie? Obecnie Portless wspiera macOS i Linux. Wsparcie dla Windowsa nie jest oficjalnie potwierdzone.

Czy muszę uruchamiać proxy ręcznie? Nie. Proxy auto-startuje przy pierwszym uruchomieniu aplikacji przez portless <nazwa> <polecenie>. Możesz uruchomić go ręcznie przez portless proxy start, ale nie jest to wymagane.

Czy mogę używać własnej domeny zamiast .localhost? Portless używa .localhost, który jest specjalną domeną rozwiązywaną lokalnie przez przeglądarki bez konfiguracji DNS. Własne domeny wymagałyby edycji /etc/hosts.

Czy port 1355 jest sztywno ustawiony? Nie. Możesz zmienić port proxy przez flagę -p lub zmienną PORTLESS_PORT. Port 1355 to domyślna wartość, która nie wymaga sudo.

Co się stanie, jeśli zamknę terminal? Proxy daemon działa w tle i przetrwa zamknięcie terminala. Aplikacja uruchomiona przez Portless zakończy się normalnie jak każdy inny proces.

Czy Portless spowalnia aplikację? Narzut reverse proxy jest minimalny. W przypadku HTTPS z HTTP/2 aplikacja może nawet działać szybciej dzięki multipleksowaniu połączeń.

Czy mogę wyłączyć Portless tymczasowo? Tak. Ustaw PORTLESS=0 przed poleceniem: PORTLESS=0 portless myapp next dev. Aplikacja uruchomi się na domyślnym porcie.

Podsumowanie

Portless rozwiązuje problem, który wydaje się trywialny, dopóki nie dotknie Cię po raz dziesiąty w tym tygodniu. Numery portów to zbędny detal kognitywny - Portless zamienia je na czytelne nazwy, które są stabilne, izolowane i współdzielone między członkami zespołu.

Narzędzie wymaga zerowej konfiguracji. Jeden npm install -g portless, dodanie portless <nazwa> przed poleceniem dev i gotowe. Proxy startuje automatycznie, port jest przydzielany losowo, a przeglądarka widzi stabilny adres nazwa.localhost:1355.

Dla projektów z wieloma serwisami - monorepo, mikroserwisy, frontend + backend + docs - Portless eliminuje cały zestaw problemów: konflikty portów, mieszanie ciasteczek, ręczną konfigurację CORS i przekazywanie portów w zespole. Do tego HTTPS z HTTP/2 jedną flagą.

Darmowe, open source (Apache-2.0), stworzone przez Vercel Labs.

Portless - no more port juggling in local development

Port 3000 is taken. Port 3001 too. Which one was the backend again?

Local development in 2026 looks something like this: frontend on port 3000, backend API on 4000, documentation on 3001, admin panel on 3002. You start a fifth service and get EADDRINUSE - port taken. You switch to 3005. A day later you can't remember which project runs on which port. You open a tab with localhost:3000, but it's a completely different app than yesterday. Cookies and localStorage from the previous project bleed into the current one.

If this sounds familiar, Portless solves exactly this problem.

What is Portless?

Portless is a tool created by Vercel Labs that replaces traditional localhost:PORT addresses with readable, stable names in the format appname.localhost:1355. Instead of remembering that the frontend runs on port 3000 and the API on 4000, you simply open myapp.localhost:1355 and api.myapp.localhost:1355.

Under the hood, Portless runs a reverse proxy on port 1355 that routes traffic to the appropriate applications. Each app gets a random port from the 4000-4999 range via the PORT environment variable, and the proxy maps names to ports. You never need to know these ports - you work exclusively with names.

Why Portless?

Problems with the traditional approach

Port numbers are a technical detail that shouldn't occupy a developer's mental space. And yet:

• Port conflicts - EADDRINUSE is one of the most commonly encountered errors in development. Two projects default to the same port and you have to manually resolve the conflict.
• Memory - in a monorepo with five services you need to remember five port numbers. After a week-long break from the project - good luck.
• Cookies and localStorage - the browser assigns them to the host. When you run a different project on localhost:3000 today than yesterday, it inherits the previous project's cookies.
• CORS and OAuth configuration - allowlists, redirect URIs, .env files - everything depends on specific ports. Changing a port means a chain of configuration changes.
• Team communication - "run the backend on 4000" - but what if your colleague has a different project there?
• AI agents - tools like Cursor, Claude Code, or Copilot guess ports or hardcode default values. In a monorepo this is a recipe for problems.

What Portless gives you

How does it work?

Portless architecture is based on three elements:

Browser                       Proxy                    Application
myapp.localhost:1355  →  port 1355 (daemon)  →  port 4123 (next dev)
api.myapp.localhost:1355  →  port 1355 (daemon)  →  port 4567 (express)

1. Proxy daemon listens on port 1355 (or another configured port)
2. The portless wrapper starts the application with a random port assigned to the PORT variable
3. Proxy registers the route - maps the hostname to the assigned port
4. Browser connects to name.localhost:1355, proxy forwards to the correct port

Most frameworks (Next.js, Vite, Express, Nuxt, Remix) automatically respect the PORT variable, so you don't need to change anything in your project configuration.

Installation

Requirements

• Node.js 20 or higher
• macOS or Linux

Global installation

npm install -g portless

Quick start

portless myapp next dev

This command does three things at once:

• Starts the proxy daemon (if not already running)
• Assigns a random port and sets the PORT variable
• Registers the route myapp.localhost:1355

Open http://myapp.localhost:1355 in your browser and you're done.

CLI commands

Running applications

The basic pattern is portless <name> <command>:

portless myapp next dev

Application available at http://myapp.localhost:1355.

portless api.myapp pnpm start

Subdomain - available at http://api.myapp.localhost:1355.

portless docs.myapp next dev

Another subdomain - http://docs.myapp.localhost:1355.

Proxy management

portless proxy start

Starts the proxy daemon in the background. Usually you don't need to do this manually, as the proxy auto-starts when you first run an application.

portless proxy stop

Stops the proxy daemon.

portless proxy start --foreground

Runs the proxy in the foreground - useful for debugging, as logs go directly to the terminal.

Listing routes

portless list

Displays active routes - which names are mapped to which ports.

package.json integration

Instead of running portless manually, add it to your project scripts:

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

Now pnpm dev automatically starts the proxy and assigns a stable name. Every team member uses the same address myapp.localhost:1355.

Monorepo with multiple services

{
  "packages": {
    "web": {
      "scripts": {
        "dev": "portless web.myapp next dev"
      }
    },
    "api": {
      "scripts": {
        "dev": "portless api.myapp node server.js"
      }
    },
    "docs": {
      "scripts": {
        "dev": "portless docs.myapp next dev"
      }
    }
  }
}

Three services, three readable addresses:

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

HTTPS and HTTP/2

Enabling HTTPS

portless proxy start --https

Portless generates local TLS certificates and starts the proxy with HTTP/2 support. Addresses change to https://myapp.localhost:1355.

Trusting the certificate

The browser will display an untrusted certificate warning. To avoid this:

sudo portless trust

This command adds the local CA (Certificate Authority) to the system's trusted certificate store. You only need to run it once.

Custom certificates

If you have your own certificates (e.g., from mkcert):

portless proxy start --cert ./cert.pem --key ./key.pem

Why HTTP/2 matters in development

Browsers limit HTTP/1.1 to 6 concurrent connections per host. Dev servers that serve many unbundled files (Vite, Nuxt in dev mode) can load slower because of this. HTTP/2 multiplexes all requests over a single connection, eliminating this limitation.

Permanently enabling HTTPS

Instead of adding the --https flag every time:

export PORTLESS_HTTPS=1

Add this to your .bashrc or .zshrc to enable HTTPS by default.

Environment variables

Portless can be configured via environment variables:

Disabling Portless for a single command

Sometimes you want to run an application directly, without the proxy:

PORTLESS=0 portless myapp next dev

The application will start on its default port, bypassing the proxy.

Custom proxy port

The default port 1355 doesn't require sudo. If you want to use a port below 1024 (e.g., 80 or 443):

sudo portless proxy start -p 443 --https

Then addresses look like this: https://myapp.localhost - no port number in the URL.

State directory

Portless stores routes, PID files, and port information:

• Ports < 1024 (requires sudo): /tmp/portless (shared between root and user)
• Ports >= 1024: ~/.portless (user-scoped)

Framework compatibility

Portless works with any framework that respects the PORT environment variable. In practice, this covers the vast majority of popular tools:

If your framework requires manual port configuration, make sure it reads from process.env.PORT.

Portless and AI agents

One of the less obvious uses of Portless is working with coding agents. Tools like Cursor, Claude Code, Copilot, or Codex often need to know what address an application runs at - for example, to open a preview, test an API endpoint, or verify that a change works.

The problem is that agents don't know for certain which port the server runs on. In a monorepo the situation is even worse - five services on five ports, and the agent only sees console output.

With Portless, names are stable and predictable. The agent knows that the frontend is always myapp.localhost:1355 and the API is api.myapp.localhost:1355. No guessing.

Comparison with alternatives

Portless doesn't replace Caddy or nginx in production. It's a strictly development tool, optimized for quick start and zero configuration.

Practical scenarios

Solo project with frontend and backend

portless web next dev
portless api node server.js

Two commands, two stable addresses. No configuration files.

Monorepo with Turborepo

In turbo.json you define dev tasks, and in each package's package.json you use Portless:

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

turbo dev will start all services in parallel, each with its own .localhost address.

Team collaboration

The entire team installs Portless globally and uses the same names in package.json scripts. No need to synchronize ports, edit /etc/hosts, or update documentation. The address myapp.localhost:1355 is the same on every machine.

Testing webhooks

If you're testing webhooks with HTTPS, Portless with the --https flag gives you a local TLS certificate without needing to configure ngrok or Cloudflare Tunnel for basic testing.

Frequently asked questions

Does Portless work on Windows? Currently Portless supports macOS and Linux. Windows support is not officially confirmed.

Do I need to start the proxy manually? No. The proxy auto-starts when you first run an application via portless <name> <command>. You can start it manually with portless proxy start, but it's not required.

Can I use a custom domain instead of .localhost? Portless uses .localhost, which is a special domain resolved locally by browsers without DNS configuration. Custom domains would require editing /etc/hosts.

Is port 1355 hardcoded? No. You can change the proxy port with the -p flag or the PORTLESS_PORT variable. Port 1355 is the default value that doesn't require sudo.

What happens if I close the terminal? The proxy daemon runs in the background and survives terminal closure. The application started through Portless will terminate normally like any other process.

Does Portless slow down the application? The reverse proxy overhead is minimal. With HTTPS and HTTP/2, the application may even run faster thanks to connection multiplexing.

Can I temporarily disable Portless? Yes. Set PORTLESS=0 before the command: PORTLESS=0 portless myapp next dev. The application will start on its default port.

Summary

Portless solves a problem that seems trivial until it hits you for the tenth time this week. Port numbers are unnecessary cognitive overhead - Portless replaces them with readable names that are stable, isolated, and shared across team members.

The tool requires zero configuration. One npm install -g portless, add portless <name> before your dev command, and you're done. The proxy starts automatically, a port is assigned randomly, and the browser sees a stable address name.localhost:1355.

For projects with multiple services - monorepo, microservices, frontend + backend + docs - Portless eliminates a whole class of problems: port conflicts, cookie bleeding, manual CORS configuration, and port sharing across the team. Plus HTTPS with HTTP/2 in a single flag.

Free, open source (Apache-2.0), built by Vercel Labs.