로컬에서 개발·테스트

로컬에서 개발·테스트 (Develop and test locally)

샌드박스의 개인 런타임으로 이미지를 빌드하고, 테스트를 실행하고, 로컬 서비스를 연결하는 방법을 알아볼게요.

출처: 문서

본문

이 페이지는 로컬 샌드박스, 호스트 서비스, 로컬 포트 매핑을 설명해요. 클라우드 엔드포인트는 포트 노출을 참고하세요.

샌드박스의 개인 런타임으로 이미지를 빌드하고, 테스트를 실행하고, 샌드박스 경계를 가로질러 로컬 도구를 개발 서비스에 연결하세요.

샌드박스 안에서 빌드·테스트 (Build and test inside a sandbox)

에이전트는 샌드박스 안에서 sudo 접근이 있으므로 패키지를 설치하고, 데이터베이스를 시작하고, 테스트 의존성을 실행하고, 필요한 환경을 준비할 수 있어요. 설치된 패키지는 샌드박스 수명 동안 유지돼요. 반복 설정에는 Customize로 환경을 템플릿이나 kit로 패키징하세요.

에이전트는 Docker 이미지를 빌드하고, 컨테이너를 실행하고, Compose를 사용할 수도 있어요. 모든 것이 샌드박스의 개인 Docker 데몬 안에서 실행되므로, 에이전트가 시작한 컨테이너는 호스트의 docker ps에 절대 나타나지 않아요. 샌드박스를 제거하면 안의 모든 이미지, 컨테이너, 볼륨이 함께 삭제돼요.

이 패턴은 에이전트가 프로젝트의 테스트 스위트를 실행하거나 시작한 서비스를 검사해야 하는 작업에 잘 맞아요. 호스트에서 그 서비스에 도달해야 한다면 샌드박스를 만들 때 포트를 게시하거나, 나중에 sbx ports로 게시하세요.

로컬 서비스 (Local services)

샌드박스 에이전트가 개발 서버를 시작하거나, 에이전트가 호스트에서 실행 중인 서비스를 호출해야 할 때 이 워크플로우를 사용하세요.

샌드박스 안의 서비스 접근 (Accessing services in the sandbox)

샌드박스는 네트워크로 격리되어 있어요 — 브라우저나 로컬 도구는 기본적으로 안에서 실행되는 서버에 도달할 수 없어요. 8080:3000 포트 매핑은 샌드박스 포트 3000을 호스트 포트 8080에 게시해요.

필요한 포트를 알고 있다면 샌드박스를 만들 때 게시하세요:

$ sbx run --publish 8080:3000 --name my-sandbox claude

기존 샌드박스는 sbx ports로 호스트에서 트래픽을 전달하세요. 중지된 로컬 샌드박스에 포트를 게시하면 먼저 시작돼요.

일반적인 경우: 에이전트가 개발 서버나 API를 시작했고, 브라우저에서 열거나 테스트를 실행하고 싶을 때.

$ sbx ports my-sandbox --publish 8080:3000
$ open http://localhost:8080

직접 고르는 대신 OS가 빈 호스트 포트를 고르게 하려면 샌드박스 포트만 지정하세요. sbx ports로 어떤 호스트 포트가 할당됐는지 확인하세요:

$ sbx ports my-sandbox --publish 3000
$ sbx ports my-sandbox

sbx ls는 각 샌드박스 옆에 활성 포트 매핑을 보여주고, sbx ports는 상세히 나열해요:

$ sbx ls
SANDBOX         AGENT   STATUS   PORTS                    WORKSPACE
my-sandbox      claude  running  127.0.0.1:8080->3000/tcp4 /home/user/proj

포트 전달을 중지하려면:

$ sbx ports my-sandbox --unpublish 8080:3000

서비스가 도달 가능하려면 샌드박스 안에서 127.0.0.1만이 아니라 모든 인터페이스에서 수신해야 해요. IPv4는 0.0.0.0, IPv4·IPv6 둘 다는 [::]에 바인딩하세요. 대부분의 개발 서버는 이를 위해 --host 0.0.0.0 같은 플래그가 필요해요.

호스트에서 게시된 포트는 다른 프로토콜을 이름 붙이지 않는 한 IPv4(127.0.0.1)에 바인딩되므로, http://localhost:<port>/는 해석기가 localhost에 고르는 주소와 무관하게 IPv4에서 수신하는 서비스에 도달해요. --publish [::1]:8080:3000처럼 명시적 IPv6 호스트 주소를 이름 붙이면 기본 프로토콜이 tcp6이 돼요. 두 패밀리에 게시하려면 --publish 8080:3000/tcp, IPv6만이면 /tcp6을 사용하세요. 두 경우 모두 샌드박스 서비스가 IPv6([::]에 바인딩)에서도 수신해야 해요. 그렇지 않으면 ::1로 도착한 클라이언트는 연결이 받아들여진 뒤 reset돼요.

게시된 포트는 재시작에도 유지돼요: 샌드박스나 데몬이 재시작되면 sbx가 다시 게시해요. 명시적 호스트 포트는 재사용되고, --publish 3000처럼 OS 할당 호스트 포트로 게시한 포트는 시작할 때마다 다른 호스트 포트를 받아요. sbx ports my-sandbox로 찾으세요. 재시작 시 명시적 호스트 포트가 이미 사용 중이면 CLI나 대시보드가 다른 포트를 고르라고 안내해요. 샌드박스를 제거하면 포트가 해제돼요.

sbx run이 기존 샌드박스에 재붙을 때 --publish를 무시해요. 그 샌드박스에 포트를 게시하려면 sbx ports를 사용하세요. 전달을 중지하려면 --unpublish 8080:3000이 단일 매핑을 제거하고, --unpublish 3000은 샌드박스 포트 3000에 매핑된 모든 호스트 포트를 제거해요.

샌드박스에서 호스트 서비스 접근 (Accessing host services from a sandbox)

호스트에서 실행 중인 서비스는 host.docker.internal 호스트네임으로 샌드박스 안에서 도달할 수 있어요. 샌드박스 안에서 도달할 수 없는 127.0.0.1이나 머신의 로컬 네트워크 IP 대신 이것을 사용하세요.

샌드박스 프록시는 요청을 전달하기 전에 host.docker.internal을 localhost로 번역하므로, 네트워크 정책 허용목록에 특정 포트의 localhost 주소를 추가해야 해요:

$ sbx policy allow network localhost:11434

그런 다음 호스트 서비스를 가리키는 어떤 구성이나 요청에서든 host.docker.internal을 사용하세요. 예를 들어 샌드박스 셸에서 연결성을 확인하려면:

$ curl http://host.docker.internal:11434