portless는 로컬 개발 서버의 포트 번호를 안정적인 명명된 .localhost URL로 대체하여 개발 환경의 복잡성을 줄이는 도구입니다.

해결하는 문제:
기존 로컬 개발 환경에서 발생하는 포트 충돌(EADDRINUSE), 포트 번호 암기 어려움, 서버 변경 시 브라우저 탭 내용 혼동, 모노레포에서의 문제 증폭, AI 코딩 에이전트의 잘못된 포트 추측, localhost에서 실행되는 다른 앱 간의 쿠키 및 저장소(localStorage) 충돌, CORS allowlist나 OAuth redirect URI와 같은 설정 파일의 하드코딩된 포트 문제, 팀원과의 URL 공유 어려움, 브라우저 기록의 비효율성 등의 문제를 해결합니다.

핵심 방법론 (Core Methodology):
portless는 중앙 집중식 프록시 서버를 통해 이러한 문제들을 해결합니다. 이 프록시는 기본적으로 1355 포트에서 실행됩니다.

1. 프록시 시작: portless proxy start 명령을 통해 프록시를 명시적으로 시작하거나, $portless <name> <command>$와 같이 portless를 사용하여 앱을 실행할 때 프록시가 자동으로 시작됩니다. 이 프록시는 시스템에 단 한 번만 실행되며, sudo 권한 없이 1024 이상의 포트에서 실행 가능합니다.
2. 앱 등록 및 포트 할당: 개발자가 portless myapp next dev와 같이 특정 이름(myapp)과 함께 앱 실행 명령을 호출하면, portless는 해당 앱에 대해 4000-4999 범위의 사용 가능한 임의의 포트(예: 4123)를 할당합니다. 이 포트 정보와 앱 이름(myapp)은 portless 프록시에 등록됩니다. 대부분의 프레임워크(Next.js, Express 등)는 PORT 및 HOST 환경 변수를 자동으로 인식하여 이 할당된 포트를 사용합니다. Vite, Astro, React Router, Angular와 같이 PORT 환경 변수를 무시하는 프레임워크의 경우, portless는 자동으로 --port 및 --host 플래그를 주입합니다.
3. URL 라우팅: 앱이 등록된 후에는 $http://<name>.localhost:1355$ 형식의 안정적인 URL을 통해 앱에 접근할 수 있습니다. 예를 들어, myapp이라는 앱은 http://myapp.localhost:1355로 접근 가능하며, 서브도메인도 지원하여 http://api.myapp.localhost:1355와 같이 사용할 수 있습니다.
4. 프록시 동작:
   • 브라우저가 myapp.localhost:1355로 요청을 보냅니다.
   • 이 요청은 1355 포트에서 실행 중인 portless 프록시로 전달됩니다.
   • 프록시는 요청된 도메인(myapp.localhost)을 파싱하여 등록된 앱 이름(myapp)을 식별하고, 해당 앱에 할당된 내부 포트(예: 4123)를 조회합니다.
   • 프록시는 요청을 해당 앱이 실제로 실행 중인 localhost:4123으로 포워딩합니다.
   • 이 과정을 통해 개발자는 복잡한 포트 번호를 기억할 필요 없이, 이름으로 앱에 접근하고 모든 앱이 동일한 포트(프록시 포트)를 공유하는 것처럼 보이게 됩니다.

주요 기능 및 사용법:

• 기본 사용: $portless <name> <cmd> [args...]$
• 프록시 제어: portless proxy start, portless proxy stop
• 라우트 목록 확인: portless list
• HTTPS/HTTP/2 지원: --https 플래그를 사용하여 HTTPS 및 HTTP/2를 활성화할 수 있습니다. 첫 실행 시 CA(Certificate Authority)를 시스템 신뢰 저장소에 추가하기 위해 한 번의 sudo 권한이 필요하며, 이후에는 브라우저 경고 없이 작동합니다. 사용자 정의 인증서(--cert, --key) 사용도 가능합니다.
• 포트 변경: --port 플래그나 PORTLESS_PORT 환경 변수로 프록시 포트를 변경할 수 있습니다.
• 프록시 우회: $PORTLESS=0$ 또는 $PORTLESS=skip$ 환경 변수를 설정하여 portless 프록시를 우회하고 명령을 직접 실행할 수 있습니다.
• 상태 디렉터리: portless는 라우트 정보, PID 파일 등을 ~/.portless (기본) 또는 /tmp/portless (1024 미만 포트 사용 시)에 저장합니다. PORTLESS_STATE_DIR 환경 변수로 경로를 변경할 수 있습니다.

portless 앱 간 프록시 설정:
프론트엔드 개발 서버(예: Vite, Webpack)에서 portless로 실행되는 백엔드 API로 요청을 프록시할 경우, Host 헤더를 재작성하도록 changeOrigin: true 설정을 해야 합니다. 이 설정이 없으면 portless가 508 Loop Detected 오류를 반환하며 무한 루프에 빠질 수 있습니다.

요구 사항:
Node.js 20+ 버전과 macOS 또는 Linux 환경이 필요합니다.