Coasts – AI Agent를 위한 Containerized 로컬 개발 환경 격리 도구

Who Should Read

Claude Code, Codex 같은 AI 코딩 에이전트를 여러 개 동시에 돌리는 개발자, 또는 git worktree를 활용해 병렬 개발을 하다가 포트 충돌이나 환경 간섭 때문에 고생한 경험이 있는 개발자.

Core Mechanics

• Coasts(Containerized Hosts)는 단일 머신에서 완전한 개발 환경 인스턴스를 N개 병렬로 띄울 수 있는 CLI 도구다. git worktree마다 독립된 컨테이너 환경을 부여해서, 여러 AI 에이전트가 동시에 작업해도 포트 충돌이나 파일 간섭이 생기지 않는다.
• 기존 코드를 전혀 바꾸지 않아도 된다. 프로젝트 루트에 Coastfile 하나만 추가하면 되고, 이미 docker-compose.yml을 쓰고 있다면 그것도 그대로 재사용된다. Docker를 안 쓰는 프로젝트에서도 동작한다.
• 포트 전략이 두 가지다. 하나의 coast를 'check out'해서 표준 포트(80, 3000 등)에 바인딩하거나, 다른 worktree들은 동적 포트로 접근해서 여러 환경의 진행 상황을 동시에 확인할 수 있다.
• DinD(Docker in Docker) 방식을 채택해서 각 컨테이너 안에 완전한 Docker API를 제공한다. 단순 마운트 네임스페이스 대신 DinD를 선택한 이유는 사용자의 docker-compose를 수정 없이 그대로 실행하기 위해서다. 다만 각 containerized host당 약 200MB의 오버헤드가 발생한다.
• 'shared-services' 개념을 지원해서 격리가 필요 없는 서비스(예: PostgreSQL, Redis)는 Coastfile에 선언하면 호스트 Docker 데몬에서 한 번만 실행하고 모든 coast에서 공유할 수 있다. 이를 통해 불필요한 리소스 낭비를 줄인다.
• AI 프로바이더나 에이전트 하네스에 종속되지 않는다. git worktree가 있으면 되기 때문에 Claude Code, Codex, Cursor 등 어떤 도구로도 전환이 가능하고, 환경 설정을 바꿀 필요가 없다.
• 오프라인 퍼스트 설계로 외부 서비스 의존성이 없다. 만약 Coasts 서비스 자체가 사라지더라도 로컬 워크플로우는 그대로 동작한다는 걸 설계 원칙으로 삼고 있다.
• 에이전트를 coast 안에서 직접 실행하는 건 OAuth 토큰 문제로 현재 제한적이다. Anthropic의 경우 런타임 환경이 달라지면 OAuth 토큰을 빠르게 무효화해버려서, 에이전트를 coast 내부에서 쓰려면 API 키 방식을 써야 한다. Playwright 같은 브라우저 런타임이 필요한 에이전트도 별도 세팅이 필요하다.

Evidence

• 여러 댓글에서 '이 고통을 실제로 겪어봤다'는 반응이 많았다. Codex/Claude Code를 4~5개 세션을 worktree별로 병렬로 돌리다가 포트 충돌이 너무 심해서 쓰기 힘들었다는 경험담이 나왔고, Cursor나 Devin 같은 자체 컨테이너를 제공하는 도구를 쓰거나 매번 수동으로 환경을 분리하는 식으로 대처해왔다는 이야기도 있었다.
• 유사한 문제를 specific.dev라는 서비스로 풀고 있다는 경쟁사 댓글이 있었다. 이쪽은 Docker 대신 CLI가 포트 할당을 직접 관리하고 env var로 전달하는 방식을 택했는데, Mac에서의 Docker 경험이 여전히 좋지 않아서 Docker를 피하려 했다고 밝혔다. 같은 설정을 프로덕션에도 그대로 배포할 수 있다는 장점도 언급했다.
• MCP 서버 격리 용도로 쓸 수 있다는 흥미로운 활용 아이디어가 나왔다. 현재 MCP 서버들이 로컬 stdio 프로세스로 돌아가는데, 서드파티 MCP 서버를 설치할 때마다 보안 우려가 생기는 문제를 이 도구로 해결할 수 있다는 것이다. stdio-to-HTTP 브릿징을 지원하면 로컬 MCP 서버를 리모트로 노출할 수 있을 거라는 제안도 있었다.
• 에이전트가 'coast exec' 경계를 얼마나 신뢰성 있게 지키냐는 질문이 나왔다. 특히 에이전트가 서브에이전트를 spawn했을 때 격리 설정이 상속되는지 여부가 불명확하다는 지적이었다. 이 부분은 현재까지 명확한 답변이 없는 상태다.
• hot 전략에서 기술적인 엣지 케이스 질문이 있었다. DinD 컨테이너 안에서 umount -l /workspace + mount --bind + mount --make-rshared를 할 때, lazy unmount 때문에 파일 와처(file watcher)가 구 worktree의 fd를 계속 붙잡고 있는 동안 새 마운트가 이미 활성화될 수 있다는 문제 제기였다. 이 경우 stale 경로에 계속 쓰는 일이 생기는지, 아니면 inotify 이벤트로 자연스럽게 복구되는지를 물었는데, 답변이 달리지 않아 미해결로 보인다.

How to Apply

• Claude Code나 Codex를 여러 feature branch에서 동시에 돌리고 싶은 경우, 프로젝트 루트에 Coastfile을 추가하고 'eval $(curl -fsSL https://coasts.dev/install)'로 설치한 뒤, 각 git worktree마다 coast를 띄우면 포트 충돌 없이 N개 에이전트 세션을 병렬로 운영할 수 있다.
• 이미 docker-compose.yml이 있는 프로젝트라면 Coastfile에서 그대로 참조할 수 있다. PostgreSQL, Redis처럼 격리가 불필요한 서비스는 shared-services로 선언해서 각 coast 간에 공유하면 메모리 절약이 가능하다. coast당 200MB 오버헤드가 있으므로 공유 가능한 서비스는 최대한 shared로 선언하는 게 유리하다.
• 서드파티 MCP 서버를 로컬에서 안전하게 실행하고 싶다면 Coasts로 MCP 서버를 격리 컨테이너에서 돌리는 방식을 검토해볼 수 있다. 현재 stdio-to-HTTP 브릿징은 공식 지원이 아니지만, 격리 자체는 가능하므로 신뢰하기 어려운 서드파티 MCP 서버의 보안 리스크를 줄이는 용도로 실험해볼 만하다.

Code Example

# 설치
eval "$(curl -fsSL https://coasts.dev/install)"

# Coastfile 예시 (프로젝트 루트에 추가)
# docker-compose.yml을 그대로 사용하는 경우
compose: docker-compose.yml

# 격리 불필요한 서비스는 shared로 선언 (리소스 절약)
shared-services:
  - postgres
  - redis

# 개발 환경 인스턴스 실행 (각 worktree마다)
# coast up  # 현재 worktree에 coast 실행
# coast checkout <worktree>  # 특정 worktree를 캐노니컬 포트에 바인딩
# coast exec <worktree> <command>  # 특정 coast 내부에서 명령 실행

Terminology

Related Resources

• https://github.com/coast-guard/coasts
• https://coasts.dev
• https://specific.dev