# 로컬에서 포트 번호와 작별하기(?) **내가 노드 서버를 언제 켜놓았더라?** 하면서 새로운 포트번호의 `localhost` 서버가 실행되어 포트 번호를 직접 입력해주었던 경험.. 그래서 포트 번호를 `3001`로 바꾸고, API 서버는 `8080`인지 `3001`인지 헷갈리고, 어제 열어둔 브라우저 탭은 이미 죽은 서버를 가리키는 문제점들이 모든 프론트엔드 개발자라면 한번 쯔음 모두 경험해본다. 거기에 요즘 AI 코딩 에이전트까지 쓰게 되면 문제가 더 심해지는데, 에이전트가 서비스 포트를 추측하다가 틀려서 엉뚱한 곳에 요청을 보내는 일이 생긴다. 이 문제들은 사실 전부 포트 번호라는 개념에서 비롯된다. 포트 번호는 원래 개발자가 매번 의식해야 할 대상이 아니다. 네트워크 계층의 구현 세부사항인데, 어쩌다 보니 우리가 매일 외우고 관리해야 하는 것이 되어버렸다. **Portless**는 바로 이 문제점들을 지적하기 위해 나온 개념이다. --- ## Portless가 무엇일까? [GitHub - vercel-labs/portless: Replace port numbers with stable, named local URLs. For humans and agents.](https://github.com/vercel-labs/portless) > 포트 번호를 이름 기반의 안정적인 로컬 URL로 바꿔주는 도구 `localhost:3000` 대신 `[my-app.localhost](https://my-app.localhost)` 같은 URL로 앱에 접근할 수 있게 된다. 그리고 이 URL은 세션이 바뀌어도, 컴퓨터를 껐다 켜도 항상 동일하게 유지된다. 내부적으로는 경량 로컬 프록시가 동작하는 방식인데, 실제 앱은 여전히 포트에 바인딩되지만 그 포트를 Portless가 알아서 관리해준다. 개발자는 포트를 몰라도 되는 것이다. `4000~4999` 범위에서 빈 포트를 자동으로 찾아 `PORT` 환경변수로 주입하고, `HOST`는 `127.0.0.1`로 설정해 IPv4 루프백에 바인딩한다. - 기존 방식 - [http://localhost:3000](http://localhost:3000) - Portless 사용 시 - [http://my-app.localhost](http://my-app.localhost) --- ## 어떤 문제를 해결하려고 했을까? ### 포트 충돌과 관리 피로 멀티 서비스 프로젝트를 하다 보면 포트 관리가 은근히 번거롭다. 프론트엔드는 `3000`, 백엔드 API는 `8080`, 어드민은 `3001`... 팀마다 포트 번호 컨벤션도 다 다르고, 로컬 환경에 다른 뭔가가 실행 중이면 충돌이 생긴다. `EADDRINUSE`라는 에러를 처음 봤을 때의 당혹감을 기억하는 사람이 많을 것이다. ### AI 에이전트 환경에서의 신뢰성 문제 요즘 Claude, Cursor 같은 AI 에이전트를 개발에 적극적으로 활용하는 경우가 많아졌는데, 에이전트가 가장 헤매는 부분 중 하나가 바로 서비스 위치다. "API 서버가 어디서 실행 중이야?"라는 질문에 에이전트가 `3001`을 시도해보고, `8080`을 시도해보고... 이게 생각보다 자주 발생하는 문제다. `Portless` 를 쓰면 URL이 항상 예측 가능하기 때문에 `[AGENTS.md](https://AGENTS.md)`에 한 번만 명시해두면 에이전트가 세션이 바뀌어도 정확한 위치를 참조할 수 있다. ### Git Worktree 환경에서의 URL 충돌 Git worktree를 사용해서 여러 브랜치를 동시에 작업하는 경우, 각 워크트리마다 다른 포트를 수동으로 설정해야 하는 번거로움이 있다. Portless는 워크트리를 자동으로 감지하고 브랜치명을 서브도메인으로 붙여준다. - main branch - [my-app.localhost](https://my-app.localhost) - feature/login branch - [feature-login.my-app.localhost](https://feature-login.my-app.localhost) 설정 파일 하나 건드리지 않아도 각 워크트리가 자기만의 URL을 가지게 된다. --- ## Portless의 주요 특징 ### Named URL : 이름 기반 안정적인 URL `.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` 플래그를 자동으로 주입해준다. 사용자가 따로 설정할 게 없다. ### 설치 및 사용 방법 전역 설치 한 번이면 충분하고, 프로젝트별로 의존성을 추가할 필요가 없다. ```javascript 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 기반으로 개발하면서 포트 관리의 번거로움을 느끼고 있다면, 한 번쯤 써볼 만한 가치가 충분히 있을 것이라 생각이 든다. 얼른 레이어에 적용을 해봐야겠다 ^,^ For the site tree, see the [root Markdown](https://slashpage.com/timmy.md).