내가 노드 서버를 언제 켜놓았더라? 하면서 새로운 포트번호의 localhost 서버가 실행되어 포트 번호를 직접 입력해주었던 경험.. 그래서 포트 번호를 3001로 바꾸고, API 서버는 8080인지 3001인지 헷갈리고, 어제 열어둔 브라우저 탭은 이미 죽은 서버를 가리키는 문제점들이 모든 프론트엔드 개발자라면 한번 쯔음 모두 경험해본다.
거기에 요즘 AI 코딩 에이전트까지 쓰게 되면 문제가 더 심해지는데, 에이전트가 서비스 포트를 추측하다가 틀려서 엉뚱한 곳에 요청을 보내는 일이 생긴다. 이 문제들은 사실 전부 포트 번호라는 개념에서 비롯된다. 포트 번호는 원래 개발자가 매번 의식해야 할 대상이 아니다. 네트워크 계층의 구현 세부사항인데, 어쩌다 보니 우리가 매일 외우고 관리해야 하는 것이 되어버렸다. Portless는 바로 이 문제점들을 지적하기 위해 나온 개념이다.
localhost:3000 대신 my-app.localhost 같은 URL로 앱에 접근할 수 있게 된다. 그리고 이 URL은 세션이 바뀌어도, 컴퓨터를 껐다 켜도 항상 동일하게 유지된다. 내부적으로는 경량 로컬 프록시가 동작하는 방식인데, 실제 앱은 여전히 포트에 바인딩되지만 그 포트를 Portless가 알아서 관리해준다. 개발자는 포트를 몰라도 되는 것이다. 4000~4999 범위에서 빈 포트를 자동으로 찾아 PORT 환경변수로 주입하고, HOST는 127.0.0.1로 설정해 IPv4 루프백에 바인딩한다.
멀티 서비스 프로젝트를 하다 보면 포트 관리가 은근히 번거롭다. 프론트엔드는 3000, 백엔드 API는 8080, 어드민은 3001... 팀마다 포트 번호 컨벤션도 다 다르고, 로컬 환경에 다른 뭔가가 실행 중이면 충돌이 생긴다. EADDRINUSE라는 에러를 처음 봤을 때의 당혹감을 기억하는 사람이 많을 것이다.
AI 에이전트 환경에서의 신뢰성 문제
요즘 Claude, Cursor 같은 AI 에이전트를 개발에 적극적으로 활용하는 경우가 많아졌는데, 에이전트가 가장 헤매는 부분 중 하나가 바로 서비스 위치다. "API 서버가 어디서 실행 중이야?"라는 질문에 에이전트가 3001을 시도해보고, 8080을 시도해보고... 이게 생각보다 자주 발생하는 문제다. Portless 를 쓰면 URL이 항상 예측 가능하기 때문에 AGENTS.md에 한 번만 명시해두면 에이전트가 세션이 바뀌어도 정확한 위치를 참조할 수 있다.
Git Worktree 환경에서의 URL 충돌
Git worktree를 사용해서 여러 브랜치를 동시에 작업하는 경우, 각 워크트리마다 다른 포트를 수동으로 설정해야 하는 번거로움이 있다. Portless는 워크트리를 자동으로 감지하고 브랜치명을 서브도메인으로 붙여준다.
.localhost 도메인은 대부분의 브라우저에서 127.0.0.1로 자동 해석된다. 별도의 /etc/hosts 설정이나 DNS 설정 없이 바로 동작하는 것이다. 그리고 이 URL은 세션이 끝나도, 재시작해도 동일하게 유지되기 때문에 팀 문서나 에이전트 설정에 적어두기 딱 좋다.
HTTP/2 지원 : 개발 서버 성능 향상
브라우저는 HTTP/1.1에서 호스트 하나당 동시 커넥션을 6개로 제한한다. 최근 Vite처럼 번들링 없이 수백 개의 모듈 파일을 그대로 서빙하는 개발 서버에서는 이게 실제 병목이 된다. 파일 하나하나가 HTTP 요청이 되다 보니 큐가 쌓이는 것이다. HTTP/2는 단일 커넥션에서 모든 요청을 멀티플렉싱으로 처리하기 때문에 이 제약이 사라진다. 개발 서버 로딩이 눈에 띄게 빨라지는 걸 느낄 수 있다.
어떻게 로컬 환경에서 HTTP/2를 지원할까?
HTTP/2는 브라우저 레벨에서 HTTPS가 필수다. 브라우저들이 보안상의 이유로 HTTP/2를 TLS(HTTPS) 위에서만 지원하도록 결정했기 때문이다. 기술 스펙상 평문 HTTP/2(h2c)도 존재하긴 하는데, 실제 브라우저는 아무것도 지원하지 않는다. 그래서 기존 localhost:3000은 plain HTTP → 브라우저가 HTTP/1.1로만 통신하게 된다.
Portless는 이 문제를 이렇게 해결한다
1.
로컬 프록시를 띄우면서 TLS 인증서를 자동 생성
2.
해당 인증서를 로컬 시스템에 자동으로 신뢰 등록 (브라우저 경고 없음)
3.
브라우저 ↔ Portless 프록시 구간이 HTTPS/HTTP/2로 통신
4.
Portless 프록시 ↔ 실제 앱 구간은 내부적으로 HTTP/1.1
즉, 앱 자체는 그대로인데 브라우저 입장에서는 HTTPS/HTTP/2로 접근하게 되는 것이다.
그래서 Vite처럼 파일을 잘게 쪼개서 수백 개 요청이 생기는 개발 서버에서 체감 속도 차이가 나는 것이다.
프레임워크 자동 호환
PORT 환경변수를 무시하는 프레임워크들이 꽤 있다. Vite, Astro, React Router, Angular 등이 그렇다. Portless는 이런 프레임워크를 자동으로 감지해서 --port, --host 플래그를 자동으로 주입해준다. 사용자가 따로 설정할 게 없다.
설치 및 사용 방법
전역 설치 한 번이면 충분하고, 프로젝트별로 의존성을 추가할 필요가 없다.
npm install -g portless
사용법은 기존 dev 스크립트 앞에 portless run --만 붙이면 된다.
# Enable HTTPS (one-time setup, auto-generates certs)
portless proxy start --https
# Next.js
portless myapp next dev
# -> https://myapp.localhost
# Vite
portless myapp vite
# Without --https, runs on port 1355
# -> http://myapp.localhost:1355
Portless의 장점
•
포트 관리에서 완전히 해방된다. 더 이상 어떤 포트를 쓸지 결정하고, 충돌을 피하고, 팀원에게 알려주는 일을 반복하지 않아도 된다.
•
세션 간 URL이 유지된다. 북마크, 팀 위키, 에이전트 설정 파일에 한 번 적어두면 영구적으로 유효하다.
•
멀티 브랜치 개발이 훨씬 편해진다. Git worktree를 쓴다면 브랜치별 URL이 자동으로 분리되기 때문에 설정 변경 없이 여러 브랜치를 동시에 띄워두고 작업할 수 있다.
•
AI 에이전트 활용도가 높아진다. 에이전트가 서비스 위치를 신뢰할 수 있게 되면 불필요한 시행착오가 줄어든다.
•
HTTP/2로 개발 서버 성능이 개선된다. 특히 모듈 수가 많은 프로젝트에서 체감 차이가 있다.
단점 및 현실적인 한계
•
macOS, Linux만 지원
◦
Windows는 현재 미지원이다. WSL2에서 동작할 수도 있다고 알려져 있지만 공식적으로 검증된 것은 아니다. Windows 환경이 메인인 팀에서는 아직 도입하기 어렵다.
•
Vercel Labs 소속 실험적 프로젝트
◦
Vercel의 메인 제품군이 아닌 Labs 소속이다. 아직 초기 단계의 실험적 도구라는 뜻인데, 안정성이나 장기 지원 여부가 보장되지 않는다. 프로덕션 환경이나 팀 전체에 강제로 도입하기보다는 개인 개발 환경에서 먼저 써보는 게 적절하다.
•
일부 프레임워크와의 비호환 가능성
◦
대부분의 주요 프레임워크는 PORT 환경변수를 잘 따르지만, APP_PORT, SERVER_PORT 같은 커스텀 변수명을 쓰는 경우는 추가 설정이 필요하거나 아예 동작하지 않을 수 있다. 사용 중인 프레임워크가 표준 PORT 변수를 지원하는지 미리 확인해볼 필요가 있다.
•
로컬 네트워크 접근 불가
◦
127.0.0.1 루프백에만 바인딩되기 때문에, 같은 Wi-Fi 네트워크에 있는 스마트폰이나 다른 기기로 개발 서버에 접근하는 테스트는 기본 설정으로는 안 된다. 모바일 반응형 테스트를 실제 기기로 하는 경우가 많다면 이 부분이 불편할 수 있다.
•
HTTPS 필수 기능 테스트의 한계
◦
기본 동작은 HTTP다. Secure Cookie, Service Worker, WebAuthn처럼 HTTPS 환경이 필수인 기능을 테스트할 때는 Portless만으로는 부족하고, 별도의 HTTPS 로컬 환경 설정이 필요하다.
Portless는 "포트 번호가 왜 개발자의 관심사여야 하지?"라는 근본적인 질문에서 출발한 도구라고 한다. 작은 불편함처럼 보이지만 매일 반복되는 마찰을 없애주고, 특히 멀티 서비스 환경이나 AI 에이전트와 함께 개발하는 경우에 실질적인 도움이 될 것이라고 생각이 든다.
다만 아직은 실험적인 단계이고 Windows 지원이 없다는 점에서 모든 팀에 맞는 도구는 아니다. 하지만 macOS나 Linux 기반으로 개발하면서 포트 관리의 번거로움을 느끼고 있다면, 한 번쯤 써볼 만한 가치가 충분히 있을 것이라 생각이 든다. 얼른 레이어에 적용을 해봐야겠다 ^,^
유유자적한 블로그 주인장 김현우입니다.
오늘도 안녕하신가요?
Subscribe
1
2
현우
실제로 사용을 해보았는데portless run next dev 를 하면 현재 프로젝트 명으로 도메인을 만들어 실행을 하는데, portless { name } next dev 이런 식으로 실행하면 https://{name}.localhost:1533 형식으로 실행이 된다. 포트는 고정이고 서브 도메인 형태처럼 바뀌는 형태.. 1533 이 가이드 문서에서는 아예 노출이 되지 않으나 실제로 실행할 때는 1533 이 계속 노출되는 형태이다.. 1533 을 없애려면 프록시가 443에서 받아서 1553으로 포워딩하는 방법이 있다.
