# portless - 포트 번호를 이름 기반 .localhost URL로 대체하는 도구

> Clean Markdown view of GeekNews topic #27116. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=27116](https://news.hada.io/topic?id=27116)
- GeekNews Markdown: [https://news.hada.io/topic/27116.md](https://news.hada.io/topic/27116.md)
- Type: news
- Author: [xguru](https://news.hada.io/@xguru)
- Published: 2026-03-02T09:51:01+09:00
- Updated: 2026-03-02T09:51:01+09:00
- Original source: [github.com/vercel-labs](https://github.com/vercel-labs/portless)
- Points: 33
- Comments: 7

## Summary

로컬 개발 환경의 **포트 충돌** 문제를 없애주는 Vercel의 오픈소스 도구 **portless**는 각 앱에 `myapp.localhost` 형태의 고유 서브도메인을 부여해 포트 번호를 기억할 필요를 없앱니다. 중앙 **프록시 프로세스**가 요청을 라우팅하며, HTTP/2와 HTTPS를 기본 지원해 빠르고 안전한 로컬 통신을 구현합니다. CLI 기반으로 단일 명령으로 앱을 실행·관리할 수 있어, 다중 프로젝트를 병행하는 개발자에게 단순하고 일관된 로컬 URL 체계를 제공합니다. 최근 업데이트로 Git Worktree 도 지원하여 이제 에이전트들에게 일 시킬 때도 충돌없이 쓰게할 수 있습니다.

## Topic Body

- 로컬 개발시 **포트 충돌** 및 **몇번 포트를 썼는지 기억해야 하는 고통**을 해결해주는 **Vercel Labs**의 오픈소스 유틸  
- 각 개발 서버에 고유한 **앱.localhost 서브도메인**을 부여해, 사람과 **AI 에이전트 모두가 인식 가능한 URL 체계 제공**  
  `next dev` 로 실행하면 `http://localhost:3000` 이어서 3000을 기억해야 하지만  
  `portless myapp next dev` 실행 시 `http://myapp.localhost:1355` 형태로 접근 가능   
  `portless api.myapp pnpm start` 같이 실행하면 `http://api.myapp.localhost:1355` 로 서브 도메인 접근도 지원   
- **프록시 기반 구조**로 동작하며, `portless proxy`가 중앙에서 요청을 라우팅  
  - 앱 실행 시 자동으로 프록시가 시작되고, 각 앱은 임의의 포트(4000–4999)에 할당  
  - 대부분의 프레임워크(Next.js, Express, Nuxt 등)는 `PORT` 환경변수를 자동 인식  
  - Vite, Astro 등 일부 프레임워크에는 **자동 플래그 주입 기능**으로 호환성 확보  
- **HTTP/2 및 HTTPS 지원**으로 빠른 페이지 로드와 안전한 로컬 통신 구현  
  - 브라우저는 HTTP/1.1을 호스트당 6개의 연결로 제한함
    - Vite/Nuxt 처럼 여러 압축 해제된 파일을 제공하는 개발 서버의 성능 저하
    - HTTP/2는 모든 요청을 단일 연결로 다중화 함
  - 자체 인증서 생성 및 시스템 신뢰 저장소 등록 자동화  
  - `--cert`, `--key` 옵션으로 **사용자 지정 인증서**도 적용 가능  
- 명령어 중심의 CLI 인터페이스 제공  
  - `portless <name> <cmd>` : 지정 이름으로 앱 실행  
  - `portless list` : 활성 라우트 목록 표시  
  - `portless proxy start/stop` : 프록시 제어  
  - `PORTLESS=0` 환경변수로 프록시 우회 실행 가능  
- **상태 관리 디렉터리**를 통해 라우트 및 PID 정보를 저장  
  - 일반 사용자 모드에서는 `~/.portless`, 루트 모드에서는 `/tmp/portless` 사용  
  - `PORTLESS_STATE_DIR`로 경로 재정의 가능  
- **Vite, webpack-dev-server** 등에서 API 프록시 설정 시 `Host` 헤더 재작성 필요  
  - 잘못된 설정 시 `508 Loop Detected` 응답으로 문제 안내  
- **Node.js 20 이상**, **macOS 및 Linux** 환경 지원  
- pnpm + Turborepo 기반 모노레포 구조  
- Apache-2.0 라이선스, TypeScript(약 74%) 코드베이스

## Comments



### Comment 52411

- Author: xguru
- Created: 2026-03-05T07:58:05+09:00
- Points: 1

워크트리 지원 하게 업데이트 되었습니다  
  
https://github.com/vercel-labs/portless/releases/tag/v0.5.2  
  
이제 자동으로 워크트리 인식해서 브랜치명을 호스트 앞에 붙여줍니다

### Comment 52184

- Author: ragingwind
- Created: 2026-03-02T19:27:17+09:00
- Points: 1

동일 프로젝트 워크트리와는 잘 맞지 않아서 사용은 안하고 있어요.

### Comment 52181

- Author: ndrgrd
- Created: 2026-03-02T18:27:11+09:00
- Points: 1

자동으로 할당을 해 주는 건가 했는데 그냥 직접 등록하는 방식이네요  
Caddy 쓰고 있는데 굳이 이걸로 바꿀 이유는 없겠네요

### Comment 52180

- Author: ksc2601
- Created: 2026-03-02T17:49:24+09:00
- Points: 1

docker + traefik + mkcert로 이미 하고있었는데 저거 쓰는게 더 편할것 같네요

### Comment 52158

- Author: bytecakelake
- Created: 2026-03-02T10:11:18+09:00
- Points: 1

유용한 글이네요

### Comment 52157

- Author: xguru
- Created: 2026-03-02T09:52:02+09:00
- Points: 1

이제 EADDRINUSE 에러랑 빠이 인가요?   
요즘 에이전트 통해서 이것 저것 개발한다고 뭐 막 띄우니까 지들끼리 충돌하고 난리던데 ㅎ

### Comment 52159

- Author: xguru
- Created: 2026-03-02T10:34:03+09:00
- Points: 1
- Parent comment: 52157
- Depth: 1

X에서 얘기가 나와서, 혹시 Docker에서 사용하는 경우 강제로 도커 대몬 PID를 넣어주면 그것도 된다고 합니다.   
  
https://github.com/vercel-labs/portless/issues/61