TL;DR

  • Valet은 Linux 서버나 Docker를 지원하는 Mac에서 실행하는 자체 호스팅 클라우드 에이전트로, 에이전트마다 컴퓨터 샌드박스를 제공함.
  • Docker Engine 24 이상, Compose v2, Claude/Codex 구독 또는 Anthropic/OpenAI API 키가 필요하며, 비공개 저장소와 풀 리퀘스트에는 GitHub 토큰을 선택적으로 사용함.
  • 저장소를 복제하고 환경 변수를 설정한 뒤 Docker Compose로 빌드·실행하며, 웹 인터페이스에서 Claude, Codex, GitHub 계정을 추가함.
  • 도메인 배포 시 웹소켓을 지원하는 리버스 프록시와 와일드카드 인증서를 구성하며, Coolify에서는 서비스 도메인과 프록시 네트워크 등의 환경 변수를 설정함.
  • 코어가 Docker 소켓을 보유하고 에이전트 컨테이너에 sudo 권한이 있으므로 샌드박스를 신뢰할 수 없는 환경으로 취급하며, 클라우드 호스트에서는 메타데이터 주소를 차단함.

요구 사항

  • Docker Engine 24 이상과 Compose v2가 설치된 Linux 서버 또는 Mac이 필요함.
  • Claude 또는 Codex 구독, 혹은 Anthropic/OpenAI API 키가 필요함.
  • 비공개 저장소 및 풀 리퀘스트 이용 시 GitHub 토큰을 선택적으로 사용할 수 있음.

설치

  • https://github.com/dropalltables/valet 저장소를 복제하고, 저장소 디렉터리로 이동함.
  • .env.example을 .env로 복사한 뒤 POSTGRES_PASSWORD, VALET_SECRET_KEY, VALET_PASSWORD를 설정함. VALET_SECRET_KEY는 openssl rand -base64 32로 생성하며, 모든 환경 변수의 설명은 .env.example에 있음.
  • docker compose --profile sandbox build로 빌드하고 docker compose up -d --build로 실행함.
  • http://localhost:3000을 열고 설정에서 Claude 설정 토큰, Codex 로그인 또는 API 키, GitHub 토큰을 추가함.

도메인 배포

  • 포트 3000을 웹소켓과 함께 리버스 프록시로 전달하고 VALET_BASE_URL을 설정함.
  • *.valet.example.com이 서버를 가리키도록 설정하고 와일드카드 인증서를 구성함. 서비스는 해당 하위 도메인에서 제공됨.

Coolify

  • 이 저장소에서 Docker Compose 리소스를 만들고 도메인 필드는 비워 둠.
  • VALET_BASE_URL, VALET_SERVICE_DOMAIN, 앱의 UUID인 VALET_PROXY_NETWORK, 프록시 설정에 추가한 DNS 챌린지 리졸버인 VALET_CERT_RESOLVER를 환경 변수로 설정함.
  • “레이블의 특수 문자 이스케이프” 옵션을 끔.

프로젝트 구성

  • .valet/setup: 복제 후 한 번 실행되는 설정 작업임.
  • .valet/resume: 깨어날 때마다 실행되는 작업임.
  • .valet/services.yaml: 계속 실행 상태로 유지할 프로세스를 지정함.
  • web: npm run dev -- --port $PORT 명령을 실행하며, browser: true로 서비스 탭에 표시함. 상태 확인 경로는 /임.
  • api: uv run uvicorn app:app --port $PORT 명령을 실행하며, 포트는 8000으로 지정함. 기본값은 자동 할당 포트임.
  • 샌드박스 안에서 valet service start|list|logs|restart|remove로 서비스를 관리하고, valet url <port>로 포트 URL을 확인함.

개발

  • bun install로 의존성을 설치하고 docker compose up -d db로 데이터베이스를 실행함.
  • VALET_DOCKER_NETWORK=valet_valet 및 VALET_REPOS_VOLUME=valet_repos 환경 변수를 지정해 bun run dev:core를 실행함.
  • bun run dev:web로 웹 개발 서버를 실행함.

보안

  • Docker 소켓은 코어가 보유하며, 포트를 공개하는 구성 요소는 웹뿐임.
  • 에이전트는 컨테이너 안에서 sudo 권한을 가지므로, 저장소 바깥의 샌드박스 환경은 신뢰할 수 없는 것으로 취급해야 함.
  • 클라우드 호스트에서는 iptables -I DOCKER-USER -d 169.254.169.254/32 -j DROP으로 메타데이터 주소를 차단함.

라이선스

  • MIT 라이선스이며 자세한 내용은 LICENSE에서 확인할 수 있음.