Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
agents-sandbox는 코딩 에이전트를 개발 환경으로부터 격리하여 보안을 강화하는 도구입니다. 사용자는 각 에이전트가 접근할 수 있는 호스트 및 네트워크 자원을 세밀하게 제어할 수 있습니다. 이는 비밀 정보 유출 위험을 줄이고, 안전한 AI 개발 워크플로우를 구축하는 데 도움을 줍니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기License: GPL-3.0
CI
Go
Release
Coverage
Security
Docs
agents-sandbox는 코딩 에이전트(coding agents)를 개발 환경의 나머지 부분으로부터 격리할 수 있도록 합니다. 사용자는 호스트 머신과 네트워크 환경의 어떤 부분이 각 에이전트에 사용 가능한지 제어권을 갖게 됩니다. agents-sandbox는 opencode, opencode2,
pi, 그리고 Claude Code의 런처 역할을 합니다. 프로젝트와 에이전트별로 전용 microsandbox VM을 구축하거나 재사용한 다음, 선택된 에이전트를 해당 VM 내부에 연결합니다. 시스템 전체에 microsandbox를 설치할 필요가 없습니다: agents-sandbox는 데이터 디렉토리 아래에서 자체 격리 런타임을 제공하며, 절대 ~/.microsandbox를 런타임으로 사용하지 않고 여기에 쓰지도 않습니다 (일회성 마이그레이션은 이전 볼륨을 복사하기 위해서만 읽습니다).
게다가 agents-sandbox는 microsandbox의 강력한 비밀 관리(secrets management) 기능을 활용하여, 에이전트에게 노출되는 비밀 정보의 양을 크게 줄여줍니다. 이 방식을 통해 유용한 어시스턴트(혹은 악성 에이전트)가 실수로 개발 비밀 정보를 공개 위키 페이지에 게시하는 것을 막을 수 있습니다 ;)
동시에, agents-sandbox는 가능한 한 뒤로 물러나서 사용자가 완전히 새로운 워크플로우에 적응할 필요가 없도록 합니다.
이 표는 호스팅된 서비스가 아닌 로컬 실행 모델들을 비교합니다. Bubblewrap/Seatbelt과 Docker는 정책 의존적인 빌딩 블록(building blocks)이므로, 항목들은 보안 점수를 할당하기보다는 일반적인 메커니즘을 요약한 것입니다.
| Category | Direct host execution | Bubblewrap / Seatbelt | Docker containers | Docker Sandboxes | agents-sandbox |
|---|---|---|---|---|
| Isolation boundary | ❌ 경계 없음; 호스트 커널 및 사용자 권한. | ⚠️ 공유 호스트 커널; 정책 정의 OS 샌드박스. | ⚠️ 공유 호스트 커널; 정책 정의 OS 샌드박스. | ✅ 별도의 microVM 및 Linux 커널. | ✅ 별도의 microVM 및 Linux 커널. |
| ... |
Sources: bubblewrap, Apple App Sandbox, Docker, 및 Docker Sandboxes. 플랫폼 요구 사항은 변경될 수 있으므로 상위 문서를 확인하십시오.
범례: 처음 네 행에 대해 ✅ = 더 강력한 격리 또는 호스트 측 처리; ⚠️ = 정책 의존적 또는 고의적으로 공유됨; ❌ = 해당 범주에서 격리가 없음. 플랫폼 및 접근성 행은 설명용입니다.
| Surface | Behavior |
|---|---|
| VM 커널 및 루트 파일 시스템 | 호스트와 분리되어, 마이크로샌드박스(microsandbox) VM 경계를 사용합니다. |
| ... |
자격 증명 경고: 편의성 설정을 통해 활성 에이전트의 호스트 구성이 기본적으로 VM에 복사됩니다. opencode의 경우, 여기에는
~/.local/share/opencode/auth.json이 포함될 수 있습니다. 자격 증명이 VM에 저장되어서는 안 되는 경우,provision-host-config: false를 설정하고, 시크릿 메커니즘(secret mechanism)을 사용하며, 자격 증명을/workspace,home:,env, 및 쓰기 가능한 마운트에서 제외하십시오. Secrets 및 Agent configuration 문서를 참조하십시오.
유용한 구분점은 에이전트가 안전해진다는 것이 아닙니다. 에이전트 프로세스가 더 이상 호스트의 커널이나 루트 파일 시스템에서 실행되지 않는다는 것입니다. VM 경계는 에이전트가 볼 수 있고 수정할 수 있는 범위를 게스트(guest)와 사용자가 의도적으로 공유하는 호스트 경로로 제한합니다. 이는 에이전트를 호스트에 직접 실행하거나 공유 커널 컨테이너에만 의존하는 것보다 강력한 경계이며, 현재 체크아웃을 편집하는 실질적인 워크플로우를 유지합니다.
다음과 같은 경우 agents-sandbox를 사용하십시오:
설치 가이드를 사용하여 agents-sandbox를 설치한 다음, 호스트 전제 조건을 확인하고 구성된 에이전트를 시작하십시오:
agents-sandbox doctor
agents-sandbox
기본 경로는 호스트에 이미 존재하는 에이전트 구성을 사용합니다. 명시적인 비밀(secret) 처리를 포함하는 독립형 설정을 위해서는 대신 샌드박스에서 구성 관리하기로 시작하세요.
--agent <name> 플래그(run, shell, build, volume, stop, kill에서 사용 가능)를 사용하여 실행하거나, 프로비저닝하거나, 관리할 코딩 에이전트를 선택할 수 있습니다. 이는 구성 파일의 설정에서도 사용할 수 있습니다.
--agent-version은 agents-sandbox가 러너 이미지에 설치하는 버전을 고정하며, 사용자 지정 기본 Dockerfile 또는 프로젝트 Dockerfile에서 이미 제공되는 에이전트를 대체하지는 않습니다.
다음 네 가지 에이전트가 내장 프로필로 제공됩니다:
opencode (기본값) — serve/attach, 작업 트리(worktree) 세션 및 GitHub-release 업그레이드 검사를 갖춘 데몬 기반 에이전트.opencode2 — opencode 2 (베타), 네이티브 설치 프로그램에서 설치되며; serve/attach, 작업 트리 세션 및 opencode 업데이트 API의 latest 채널을 통한 업그레이드 검사를 갖춘 데몬 기반. 자체 런처 구성 디렉터리(~/.config/agents-sandbox/opencode2/, 프로젝트의 경우 .agents-sandbox/opencode2/)를 소유하며, VM 구성 경로와 호스트 드롭인(host drop-in)은 ~/.config/opencode/로 유지됩니다. opencode2/ 디렉터리가 존재하지 않아도 경고 메시지와 함께 공유된 opencode/ 디렉터리로 폴백합니다 (에이전트 문서를 참조하세요).pi — pi 코딩 에이전트 (@earendil-works/pi-coding-agent, npm으로 설치되는 node 번들 — node가 필요한 유일한 에이전트)로, 대화형으로 실행되며 pi.dev를 통해 업그레이드 검사를 수행합니다.claude-code — Anthropic의 Claude Code로, 네이티브 설치 프로그램에서 설치되며; npm 레지스트리를 통해 업그레이드 검사를 수행하는 대화형 에이전트입니다.주제별 전용 문서가 있습니다. GitHub Pages에서도 문서를 찾아볼 수 있습니다.
| 주제 | 설명 |
|---|---|
| Why? | 동기(Motivation), 격리 경계(isolation boundary), 공유 데이터(shared data), 그리고 한계점들(limitations). |
| ... |
| 주제 | 설명 |
|---|---|
| CONTRIBUTING.md | agents-sandbox에 기여하는 방법에 대한 가이드라인 |
| ... |