https://github.com/vercel-labs/portless
GitHub - vercel-labs/portless: Replace port numbers with stable, named local URLs. For humans and agents.
Replace port numbers with stable, named local URLs. For humans and agents. - vercel-labs/portless
github.com
한 줄 요약
Portless는 localhost:3000처럼 외우기 어려운 로컬 개발 주소를 https://myapp.localhost처럼 이름이 있는 고정 URL로 바꿔주는 CLI 기반 로컬 프록시 도구다.
- GitHub: https://github.com/vercel-labs/portless
- 개발: Vercel Labs
- 형태: 오픈소스 CLI 개발 도구 및 npm 패키지
- 용도: 로컬 개발 서버의 포트와 URL 관리
- 라이선스: Apache 2.0
Portless는 어떤 도구인가?
웹 애플리케이션을 개발할 때 보통 다음과 같은 주소로 개발 서버에 접속한다.
http://localhost:3000
http://localhost:4000
http://localhost:5173프로젝트가 하나뿐이라면 큰 문제가 없지만, 프론트엔드·백엔드·관리자 페이지·문서 사이트처럼 여러 개발 서버를 동시에 실행하면 어떤 서비스가 어느 포트를 사용하는지 기억하기 어려워진다.
Portless를 사용하면 포트 번호 대신 애플리케이션 이름으로 접속할 수 있다.
https://web.myapp.localhost
https://api.myapp.localhost
https://admin.myapp.localhost
https://docs.myapp.localhost예를 들어 기존에는 Next.js 개발 서버가 다음 주소에서 실행되었다면,
http://localhost:3000Portless를 통해 다음과 같은 주소로 접속할 수 있다.
https://myapp.localhost즉, Portless는 로컬 개발 서버에 사람이 이해하기 쉬운 도메인 이름을 붙여주는 도구다.
라이브러리인가?
Portless를 일반적인 의미의 프로그래밍 라이브러리라고 부르기는 어렵다.
라이브러리는 보통 애플리케이션 코드에서 다음처럼 불러와 사용한다.
import something from "library";반면 Portless는 npm으로 설치한 뒤 터미널에서 명령어로 실행한다.
portless myapp next dev따라서 Portless는 다음과 같이 분류하는 것이 가장 정확하다.
npm으로 배포되는 CLI 기반 로컬 개발 도구이자 리버스 프록시
간단하게 소개할 때는 “로컬 개발용 CLI 도구” 또는 **“로컬 개발 프록시 도구”**라고 하면 된다.
Portless가 해결하는 문제
여러 서비스를 동시에 개발하는 상황을 가정해 보자.
프론트엔드: http://localhost:3000
API 서버: http://localhost:4000
관리자: http://localhost:5173
문서: http://localhost:8080이 방식에는 몇 가지 불편함이 있다.
- 서비스마다 포트 번호를 기억해야 한다.
- 이미 사용 중인 포트가 있으면 다른 포트를 찾아야 한다.
- 포트가 바뀌면 북마크와 개발 설정도 수정해야 한다.
- 여러 Git worktree를 동시에 실행하면 포트 충돌이 발생할 수 있다.
- OAuth 콜백, 쿠키, 서브도메인 등의 동작을 실제 운영 환경과 비슷하게 테스트하기 어렵다.
- 사람뿐 아니라 브라우저 자동화나 AI 에이전트도 어느 포트가 어떤 앱인지 파악해야 한다.
Portless를 적용하면 서비스의 역할을 주소에 직접 표현할 수 있다.
프론트엔드: https://myapp.localhost
API 서버: https://api.myapp.localhost
관리자: https://admin.myapp.localhost
문서: https://docs.myapp.localhost내부 포트가 바뀌어도 사용자가 접속하는 URL은 그대로 유지된다.
어떻게 작동하는가?
Portless의 핵심은 로컬에서 실행되는 리버스 프록시다.
동작 과정은 다음과 같다.
- Portless가 사용 가능한 빈 포트를 찾는다.
- 개발 서버를 해당 포트에서 실행한다.
- 애플리케이션 이름과 포트의 연결 정보를 프록시에 등록한다.
- 브라우저에서 https://myapp.localhost로 접속한다.
- Portless 프록시가 요청을 실제 개발 서버의 포트로 전달한다.
구조를 단순화하면 다음과 같다.
브라우저
↓
https://myapp.localhost
↓
Portless 로컬 프록시
↓
http://127.0.0.1:임의의 포트
↓
Next.js, Vite, Express 등의 개발 서버사용자는 내부적으로 어떤 포트가 배정되었는지 몰라도 된다.
설치 방법
Portless는 전역 설치가 권장된다.
npm install -g portless프로젝트의 개발 의존성으로 설치할 수도 있다.
npm install -D portless현재 저장소의 요구 사항은 다음과 같다.
Node.js 24 이상
Windows, macOS 또는 Linux기본 사용법
애플리케이션 이름과 실행할 명령어를 함께 입력한다.
portless myapp next dev실행 후 다음 주소로 접속할 수 있다.
https://myapp.localhostPortless는 package.json의 dev 스크립트와 프로젝트 이름을 자동으로 추론할 수도 있다. 설정이 가능한 프로젝트에서는 다음 명령만 실행해도 된다.
portless기존 package.json의 스크립트에 적용하는 방법도 있다.
{
"scripts": {
"dev": "portless run next dev"
}
}이제 평소처럼 실행한다.
npm run dev기존 주소가 다음과 같았다면,
http://localhost:3000Portless 적용 후에는 다음과 같은 주소를 사용할 수 있다.
https://myapp.localhost여러 서비스를 실행하는 예시
프론트엔드, API 서버와 문서 사이트를 각각 실행할 수 있다.
portless myapp next dev
portless api.myapp npm run start
portless docs.myapp npm run docs각 서비스에는 다음 URL로 접속한다.
https://myapp.localhost
https://api.myapp.localhost
https://docs.myapp.localhost포트 번호 대신 서비스 이름을 사용하므로 어떤 주소가 어떤 애플리케이션인지 바로 알 수 있다.
주요 특징
1. 포트 자동 할당
Portless는 사용 가능한 포트를 자동으로 찾아 개발 서버에 할당한다.
Next.js, Express, Nuxt처럼 PORT 환경변수를 지원하는 프레임워크에는 포트 번호를 환경변수로 전달한다. Vite, Astro, Angular, Expo처럼 별도의 옵션이 필요한 프레임워크에는 적절한 --port와 --host 옵션을 자동으로 추가한다.
2. HTTPS 및 HTTP/2 기본 지원
Portless는 HTTPS와 HTTP/2를 기본으로 지원한다.
최초 실행 시 로컬 인증기관을 만들고 시스템의 신뢰 저장소에 등록한다. 따라서 설정이 정상적으로 완료되면 브라우저의 인증서 경고 없이 다음과 같은 HTTPS 주소를 사용할 수 있다.
https://myapp.localhostHTTPS를 사용하지 않으려면 다음처럼 실행할 수 있다.
portless proxy start --no-tls3. 서브도메인 지원
서비스별 서브도메인을 만들 수 있다.
https://api.myapp.localhost
https://admin.myapp.localhost
https://docs.myapp.localhost마이크로서비스나 모노레포처럼 여러 애플리케이션을 함께 개발할 때 유용하다.
4. 모노레포 지원
Portless는 다음과 같은 워크스페이스 구성을 자동으로 탐색할 수 있다.
- pnpm workspace
- npm workspaces
- Yarn workspaces
- Bun workspaces
- Turborepo
루트에서 Portless를 실행하면 dev 스크립트가 있는 여러 패키지를 찾아 함께 실행할 수 있다.
5. Git worktree 지원
Git worktree에서 실행하면 브랜치 이름을 URL의 서브도메인으로 자동 적용한다.
메인 작업공간:
https://myapp.localhost
fix-ui 브랜치의 worktree:
https://fix-ui.myapp.localhost여러 브랜치의 애플리케이션을 동시에 실행해도 URL과 포트가 충돌하지 않는다.
6. 커스텀 도메인 지원
기본값인 .localhost 대신 .test 같은 다른 최상위 도메인을 사용할 수 있다.
portless proxy start --tld test접속 주소는 다음과 같다.
https://myapp.test본인이 소유한 실제 도메인의 하위 도메인을 로컬 개발에 사용할 수도 있다.
portless proxy start --tld dev.example.comhttps://myapp.dev.example.com이 방식은 .localhost 주소를 허용하지 않는 OAuth 제공자의 콜백 URL을 테스트할 때 유용하다.
7. 외부 공유 지원
Portless는 다음 방식으로 개발 서버를 다른 기기나 외부 사용자에게 공유할 수 있다.
- 같은 네트워크의 기기에 공유하는 LAN 모드
- Tailscale 네트워크 공유
- Tailscale Funnel을 통한 공개
- ngrok을 통한 공개
예를 들어 ngrok으로 공개하려면 다음과 같이 실행한다.
portless myapp --ngrok next dev유용한 명령어
현재 등록된 애플리케이션과 URL 확인:
portless list프록시, DNS, 인증서 등 상태 점검:
portless doctor로컬 인증기관을 시스템에 신뢰 등록:
portless trustPortless 프록시 직접 시작:
portless proxy start프록시 종료:
portless proxy stop정적 포트에 이름 부여하기:
portless alias myapp 3000Portless 설정과 인증서 제거:
portless clean일시적으로 Portless를 거치지 않고 기존 방식으로 실행:
PORTLESS=0 npm run dev언제 사용하면 좋은가?
Portless는 다음과 같은 상황에서 특히 유용하다.
- 여러 로컬 개발 서버를 동시에 실행할 때
- 포트 번호를 기억하거나 관리하기 싫을 때
- 프론트엔드와 API 서버를 이름으로 구분하고 싶을 때
- 모노레포에서 여러 애플리케이션을 함께 개발할 때
- Git worktree를 이용해 여러 브랜치를 동시에 실행할 때
- 로컬에서도 HTTPS 환경이 필요할 때
- OAuth 리디렉션과 서브도메인 쿠키를 테스트할 때
- 사람이나 AI 에이전트가 동일한 고정 URL로 개발 서버에 접근해야 할 때
프로젝트가 하나뿐이고 항상 동일한 포트를 사용한다면 필수 도구는 아니다. 하지만 여러 앱과 브랜치를 동시에 다루기 시작하면 포트 관리 부담을 크게 줄일 수 있다.
사용 시 알아둘 점
Portless는 현재 1.0 이전 버전이므로 업데이트 과정에서 설정이나 내부 상태 형식이 변경될 수 있다.
또한 기본 HTTPS 프록시는 일반적으로 포트 443을 사용한다. 운영체제에 따라 최초 인증서 등록이나 포트 사용을 위해 관리자 권한이 필요할 수 있다.
Portless는 기본 상태에서 로컬 루프백 주소인 127.0.0.1과 ::1에만 연결된다. 따라서 LAN 모드나 외부 공유 기능을 명시적으로 활성화하지 않는 한 다른 기기에서 직접 접근할 수 없다.
정리
Portless는 단순히 포트 번호를 숨겨주는 라이브러리가 아니다.
여러 로컬 개발 서버에 고정된 이름과 HTTPS URL을 부여하고, 실제 포트로 요청을 전달해 주는 CLI 기반 개발 프록시 도구다.
기존 방식:
http://localhost:3000
http://localhost:4000
http://localhost:5173Portless 사용 후:
https://myapp.localhost
https://api.myapp.localhost
https://admin.myapp.localhost내부 포트 번호가 바뀌어도 URL은 유지된다. 그래서 여러 서비스, 모노레포, Git worktree 또는 AI 에이전트를 활용하는 개발 환경에서 특히 편리하다.
