Agentbox - 코딩 에이전트 샌드박스

에이전트를 샌드박싱하는 완벽한 방법은 아직 없지만, 컨테이너는 실용적인 출발점이다.

Agentbox는 Docker 기반 코딩 에이전트 샌드박스로, 원래 Batrachian Toad에서 영감을 받았으며, 이제 더 많은 도구로 일반화되었다. 여러 에이전트 세션을 실행할 때 webterm과 잘 작동하는 격리된 환경을 제공한다.

기능

기본 컨테이너는 다음을 제공한다:

• 개발 환경: 일반적인 개발 도구가 포함된 Debian Stable
• 사전 설치된 코딩 에이전트: Copilot CLI, Codex, Pi
• 사전 설치된 CLI 도구: gh, Nushell, lazygit, killall
• 패키지 관리자: Homebrew와 APT, 그리고 uv와 Bun; 컨테이너 빌드는 정확한 버전 고정 없이 사용 가능한 최신 패키지를 설치한다
• 선택적 에이전트 도구: make -C ~ ...를 통해 toad, opencode, gemini, vibe 설치
• 서비스 제어: ENABLE_DOCKER, ENABLE_SSH, ENABLE_RDP로 Docker/SSH/RDP 전환
• Docker-in-Docker: 컨테이너가 privileged 모드로 실행될 때 사용 가능
• 원격 접속: SSH(ENABLE_SSH=true) 및 mosh 지원
• 워크스페이스 부트스트랩: /home/agent/workspace-skel 아래에 내장된 워크스페이스 스켈레톤과 에이전트 스킬

로드맵

• CPU 및 메모리 제한 (기본 Docker 리소스 제약)
• 네트워크 격리 옵션
• 기타 샌드박싱 기법 (gVisor, Kata Containers 등)

서비스 구성

Agentbox는 환경 변수를 사용하여 컨테이너 시작 시 어떤 서비스가 시작될지 제어한다:

• ENABLE_DOCKER=true - Docker 데몬 시작 (Docker-in-Docker 지원용)
• ENABLE_SSH=true - SSH 서버 시작 (포트 22)
• ENABLE_RDP=true - RDP 서버 시작 (포트 3389)
• AGENTBOX_ENVIRONMENT=cli|gui - 이미지 제공 환경 마커 (헤드리스/CLI의 경우 cli, 데스크톱 이미지의 경우 gui)

기본 동작: 명시적으로 활성화하지 않는 한 모든 서비스는 비활성화된다.

예시:

# Default - all services disabled
docker run -d agentbox

# Enable only Docker daemon
docker run -d -e ENABLE_DOCKER=true agentbox

# Enable Docker and SSH for development
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -p 22:22 agentbox

# Full desktop experience with all services (GUI image)
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -e ENABLE_RDP=true -p 22:22 -p 3389:3389 agentbox:gui

빠른 시작

선택적 도구 설치

컨테이너 내부에서 agent 사용자에게는 추가 도구를 설치할 수 있는 ~/Makefile이 제공된다.

make -C ~ …를 통해 설치할 수 있는 코딩 에이전트/CLI:

• toad — Batrachian Toad 설치 (uv tool 사용)
• opencode — OpenCode 설치 (Bun 사용)
• gemini — Gemini CLI 설치 (Homebrew 사용)
• vibe — mistral-vibe 설치 (uv tool 사용)

편의 타깃:

• tools — node, go, gemini, vibe 설치
• node, go — 언어 툴체인 설치 (일부 에이전트의 필수 조건)

워크스페이스 스켈레톤

Agentbox는 /home/agent/workspace-skel에 내장된 프로젝트 스켈레톤을 제공한다.

현재 /workspace로 기존 파일을 덮어쓰지 않고 복사하려면:

make init-workspace

자세한 내용은 docs/workspace-skeleton.md를 참조하라.

GUI 이미지

GUI 빌드는 :gui 태그(및 <release>-gui)로 게시되며 XFCE, XRDP, VS Code를 포함한다.

Docker Compose

권장 워크플로:

make up
make enter-toad   # or: make enter-copilot
make down

서비스 재정의가 필요하면 docker-compose.override.yml을 생성하라:

services:
  toad:
    environment:
      ENABLE_DOCKER: "true"
      ENABLE_SSH: "true"
  copilot:
    environment:
      ENABLE_DOCKER: "true"
      ENABLE_SSH: "true"

그런 다음 실행하라:

docker compose up -d

Docker 직접 사용

# Build the headless image
docker build -t agentbox .

# Build the GUI image
docker build -t agentbox:gui --target gui .

# Run the container with selected services (GUI image)
docker run -d \
  --name agentbox \
  --privileged \
  -e ENABLE_DOCKER=true \
  -e ENABLE_SSH=true \
  -e ENABLE_RDP=true \
  -p 22:22 \
  -p 3389:3389 \
  -v $(pwd):/workspace \
  agentbox:gui

Batrachian Toad 사용

컨테이너에 연결한 후:

1. Toad 설치 (필요한 경우):

make -C ~ toad

2. Toad 시작:

toad

3. 또는 특정 프로젝트 디렉터리로 시작:

toad /workspace

4. 또는 에이전트와 함께 직접 실행:

toad -a open-hands

보안 참고 사항

• 서비스 제어: 기본적으로 모든 서비스(Docker, SSH, RDP)는 비활성화된다. 환경 변수를 사용하여 필요한 것만 명시적으로 활성화하라.
• 기본 비밀번호는 취약하다 - 프로덕션 용도로는 변경하라
• 에이전트가 Docker-in-Docker를 사용할 수 있으려면 컨테이너가 privileged 모드로 실행되어야 한다 (아무것도 안 하는 것보다는 낫다)
• 비밀번호 인증 대신 SSH 키 사용을 고려하라
• 프로덕션 용도로는 불필요한 서비스를 비활성화하고 기본 자격 증명을 변경하는 것을 고려하라

크레딧

이 프로젝트는 오래된 rcarmo/docker-templates/desktop-chrome을 기반으로 하며, 사용자 환경을 업데이트했다.

라이선스

MIT