00:00:00이것은 Agent Browser, JSON Render, Skills를 만든
00:00:05Vercel Labs 팀이 제작한 CLI 도구인 Portless입니다. localhost 포트 번호를 고정된 이름으로 바꿔주죠.
00:00:10덕분에 사람이나 AI 에이전트가 항상 올바른 위치로 접속할 수 있고 포트 충돌도 방지할 수 있습니다.
00:00:15하지만 내부적으로 어떻게 작동하는지, 시스템을 망가뜨리지는 않을지 궁금하시죠?
00:00:20구독 버튼을 누르시고, 바로 시작해 보겠습니다.
00:00:21간단한 예시를 통해 Portless 사용법을 살펴보겠습니다.
00:00:26현재 3001번 포트에서 프로젝트 하나가 실행 중입니다.
00:00:30이걸 백그라운드에서 실행 중이라는 사실을 완전히 잊어버린 채로,
00:00:33비슷한 포트를 사용하는 다른 프로젝트를 실행하려고 한다면,
00:00:37주소가 이미 사용 중이라는 오류가 발생하게 됩니다.
00:00:40Portless는 바로 이런 문제를 해결하기 위해 설계되었습니다.
00:00:44여러 탭에서 서로 다른 프로젝트를 위해 여러 에이전트를 실행하고 있는데,
00:00:48이런 문제가 발생한다고 상상해 보세요.
00:00:50물론 에이전트가 직접 해결할 수도 있겠지만, 애초에 이런 일이 생기지 않도록
00:00:55항상 사용 가능한 포트가 준비되어 있다면 훨씬 더 좋겠죠.
00:00:58이제 Portless를 설치하고 Portless 프록시를 실행한 상태에서,
00:01:01portless 명령어 뒤에 원하는 호스트 이름(여기서는 xdlapi)을 입력합니다.
00:01:06호스트 이름은 무엇이든 자유롭게 정할 수 있습니다.
00:01:08그다음 실행할 명령어인 'bun run devapi'를 입력합니다.
00:01:12엔터를 치면 4000번대 범위에서 비어 있는 랜덤 포트 번호를 찾아냅니다.
00:01:16이 범위는 다른 프로그램이 사용할 가능성이 낮기 때문이죠.
00:01:20그리고 .localhost:1355를 통해 지정한 호스트 이름으로 앱을 노출해 줍니다.
00:01:25기본 포트는 Portless를 의미하는 1355입니다. 이해되시죠?
00:01:30여기를 클릭해 보면 앱이 잘 작동하는 것을 볼 수 있습니다.
00:01:34다른 앱에서도 똑같은 작업을 수행해 보면,
00:01:37이번에도 다른 빈 포트를 찾아내어 호스트 이름을 사용합니다.
00:01:40하지만 마지막에 붙는 이 포트 번호는 항상 동일하게 유지됩니다.
00:01:42사실 원한다면 이 번호도 변경할 수 있습니다.
00:01:44포트를 80으로 설정하면 콜론과 숫자 자체를 생략할 수 있습니다.
00:01:49sudo를 사용해 Portless 프록시를 80번 포트에서 시작하고,
00:01:53마찬가지로 sudo를 써서 Portless 프로세스를 실행하면,
00:01:55서브도메인과 .localhost만으로 접속할 수 있게 됩니다.
00:01:59게다가 80번 포트를 사용하면서 HTTPS 지원까지
00:02:03동시에 받을 수 있는 HTTPS 플래그도 제공합니다.
00:02:08하지만 Vite를 사용한다면 port 키에 포트 변수를 설정하고,
00:02:13host 역시 이 값으로 설정해야 합니다.
00:02:15그 이유는 영상 뒷부분에서 자세히 설명해 드릴게요.
00:02:17이외에도 Portless에는 다양한 옵션이 있습니다.
00:02:21디버깅을 위해 프록시를 포그라운드에서 실행하거나,
00:02:25디버깅이나 비상용으로 프록시 없이 명령어를 실행할 수도 있습니다.
00:02:30그런데 왜 매번 랜덤 포트 번호를 사용하는 걸까요?
00:02:33그리고 프록시는 왜 필요한 걸까요?
00:02:35어떻게 작동하는지 알아보겠습니다.
00:02:36두 가지 과정을 살펴보겠습니다.
00:02:39터미널에서 메인 Portless 명령어를 실행할 때 어떤 일이 일어나는지,
00:02:42그리고 브라우저가 Portless URL에 접속할 때 어떤 일이 생기는지 말이죠.
00:02:46여기서 'portless myapp bun start'라는
00:02:49명령어를 실행한다고 가정해 봅시다.
00:02:52먼저 호스트 이름과 실행할 명령어를 추출합니다.
00:02:56그다음 프록시가 실행 중인지 확인합니다.
00:02:59실행 중이 아니라면 프록시를 시작하죠.
00:03:01주의할 점은 프록시가 실행될 포트를 직접 설정할 수 있다는 것입니다.
00:03:06기본값은 1355입니다.
00:03:08만약 포트 번호를 1024 미만으로 설정하면,
00:03:12실행하기 전에 확인을 요청하게 됩니다.
00:03:15그 이상의 번호라면 자동으로 실행됩니다.
00:03:19다음으로 4000번에서 4999번 사이의 빈 포트를 찾습니다.
00:03:25검색 속도를 높이기 위해 포트를 무작위로 찾습니다.
00:03:29순차적으로 찾게 되면 실행 중인 프로세스가 많을 경우,
00:03:33포트를 하나씩 대조하느라 시간이 오래 걸릴 수 있기 때문입니다.
00:03:35포트를 찾으면 해당 상세 정보를 root store JSON 파일에 기록합니다.
00:03:40그런 다음 해당 포트에서 명령어를 실행하고 PORT 환경 변수에 해당 번호를 추가합니다.
00:03:47대부분의 자바스크립트 애플리케이션은 이 변수에 접근할 수 있죠.
00:03:50이제 이 부분에 집중해 보겠습니다.
00:03:52브라우저에서 portless URL(예: myapp)에 접속할 때,
00:03:56기본 포트를 사용한다면 1355번 포트가 됩니다.
00:04:00그다음 DNS 확인을 거쳐 프록시에 TCP 연결을 생성합니다.
00:04:06프록시는 호스트 이름(myapp)을 추출하고,
00:04:09그 이름을 사용해 root JSON 파일에서 해당 앱의 포트를 조회합니다.
00:04:15정확한 포트 번호를 확인하면 실제 앱으로 요청을 전달하고,
00:04:21앱은 프록시로 응답을 보낸 뒤 다시 브라우저로 전달됩니다.
00:04:26브라우저는 처음에 요청했던 1355번 포트로부터
00:04:30응답이 오기를 기다리기 때문입니다.
00:04:35이 방식은 웹소켓에서도 마법처럼 잘 작동합니다.
00:04:38주말 프로젝트 결과물 치고는 매우 인상적이죠.
00:04:40하지만 Next.js가 아닌 Vite 같은 프로젝트에서 Portless를 쓰면 문제가 생길 수 있습니다.
00:04:47우선, 고정된 번호가 아닌 PORT 변수에 할당된 랜덤 포트를 사용하기 때문에,
00:04:52앱이 해당 포트에서 실행될 수 있도록 설정해야
00:04:56프록시가 트래픽을 어디로 보낼지 알 수 있습니다.
00:05:00Vite나 유사한 번들러의 경우, 이 host 키와 값을 추가해야 할 수도 있습니다.
00:05:06알 수 없는 출처의 요청을 거부하는 보안 검사를 비활성화하기 위해서죠.
00:05:10허용된 호스트 키를 여러 값으로 시도해 봤지만 잘 안 되더군요.
00:05:16이 해결책이 다소 극단적으로 보일 수도 있지만,
00:05:19로컬에서 실행하는 것이라면 크게 걱정할 필요는 없습니다.
00:05:22Vercel Labs의 다른 프로젝트들처럼 Portless도 계속 업데이트될 예정이므로,
00:05:26이런 문제점들은 향후에 개선될 것입니다.
00:05:30윈도우 지원 같은 기능들도 포함해서 말이죠.
00:05:32Vercel Labs 이야기가 나와서 말인데, Agent Browser를 아직 안 써보셨다면 꼭 해보세요.
00:05:36에이전트가 브라우저와 상호작용할 수 있는 가장 좋은 방법입니다.
00:05:39다음 영상에서 자세히 알아보실 수 있습니다.