Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Agent Sandbox는 AI 코딩 에이전트를 격리된 로컬 샌드박스에서 안전하게 실행할 수 있도록 설계된 프로젝트입니다. 최소한의 파일 시스템 접근, 세밀하게 제어되는 네트워크 이그레스 정책, 시크릿 주입 기능 등을 통해 보안성을 극대화했습니다. CLI 및 Devcontainer를 지원하여 다양한 개발 환경에서 에이전트 사용을 지원합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Coding Assistants의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기[!WARNING]
이 프로젝트는 아직 초기 개발 단계입니다. 릴리스 간에 변경 사항이 발생할 수 있습니다.
AI 코딩 에이전트를 다음 기능을 갖춘 격리된 로컬 샌드박스에서 실행할 수 있습니다:
대상 플랫폼: Apple Silicon용 Colima + Docker Engine. 모든 Docker 호환 런타임에서 작동해야 합니다.
CLI (권장) - agentbox exec을 사용하여 터미널 세션에서 에이전트를 실행합니다.
Devcontainer - VS Code 또는 JetBrains에서 프로젝트를 열고 IDE가 컨테이너 생명주기를 관리하도록 합니다.
| Agent | CLI | VS Code | JetBrains |
|---|---|---|---|
| Claude Code | :white_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| ... |
VM과 Docker가 설치되어 있어야 합니다. 이는 다양한 방법으로 수행할 수 있습니다.
아래 지침은 Colima를 기준으로 합니다.
# 가상 머신용 colima
# 핵심 docker 엔진용 docker
# agentbox 런타임용 docker-compose
...
GitHub Releases에서 agentbox 바이너리를 다운로드하세요.
curl -fsSL https://github.com/mattolson/agent-sandbox/releases/latest/download/install.sh | sh
설치 프로그램은 기본적으로 ~/.local/bin을 사용합니다. 버전을 선택하거나 설치 디렉토리를 지정하려면 다음 명령어를 사용하세요:
curl -fsSL https://github.com/mattolson/agent-sandbox/releases/latest/download/install.sh | \
sh -s -- --version v0.17.1 --install-dir /usr/local/bin
전체 수동 설치 과정은 설치 참고 사항을 참조하세요.
agentbox init
이 명령어는 필요에 따라 프로젝트 이름, 에이전트(agent), 모드(mode), IDE를 대화형으로 요청한 후, 샌드박스를 위한 docker compose 및 네트워크 정책 파일을 생성합니다.
또한 누락된 경우 호스트 시크릿 디렉터리 ~/.config/agent-sandbox/secrets (모드 0700)를 생성합니다. 이 프록시는 아직 시크릿이 없더라도 해당 디렉터리를 읽기 전용(read-only)으로 마운트합니다. 0.17.0 버전 이하에서는 샌드박스를 시작하기 전에 직접 생성해야 합니다:
mkdir -p "${AGENTBOX_SECRET_DIR:-${HOME}/.config/agent-sandbox/secrets}"
chmod 700 "${AGENTBOX_SECRET_DIR:-${HOME}/.config/agent-sandbox/secrets}"
전체 명령어, 플래그 및 환경 변수 목록은 CLI 레퍼런스를 참조하십시오.
초기화 후 구성을 검사하려면 agentbox policy config을 사용하여 유효한 네트워크 정책을 출력하고, agentbox compose config를 사용하여 완전히 결합된 docker compose 스택을 확인하십시오.
CLI:
# 에이전트 컨테이너 내에서 셸 열기
agentbox exec
...
Devcontainer (VS Code / JetBrains):
VS Code:
JetBrains (IntelliJ, PyCharm, WebStorm 등):
사용하는 에이전트 이미지에 맞는 설정 지침을 따르십시오:
프로젝트를 재초기화하지 않고 다른 에이전트로 전환하려면:
agentbox switch --agent codex
switch는 사용자가 소유한 오버라이드 파일과 에이전트별 상태 볼륨(자격 증명, 기록)을 보존합니다. devcontainer 프로젝트의 경우 선택된 에이전트를 위해 .devcontainer/devcontainer.json 파일을 재생성합니다.
네트워크 강제 적용은 두 가지 계층으로 이루어집니다:
프록시 이미지는 기본적으로 모든 트래픽을 차단하는 정책과 함께 제공됩니다. agentbox init은 프로젝트에 대한 계층형 정책 파일과 활성 에이전트 기준선을 설정합니다.
에이전트 컨테이너는 HTTP_PROXY/HTTPS_PROXY가 프록시 사이드카를 가리키도록 설정되어 있습니다. 프록시는 mitmproxy 애드온(enforcer.py)을 실행하여 HTTPS CONNECT 터널을 호스트 정책과 비교하고, 이후 복호화된 HTTP/HTTPS 요청을 모든 스킴(scheme), 메서드(method), 경로(path) 또는 쿼리 규칙과 비교합니다. 일치하지 않는 요청은 403 응답을 받습니다.
에이전트의 iptables 방화벽(init-firewall.sh)은 Docker 브리지 네트워크를 제외한 모든 직접적인 아웃바운드를 차단합니다. 이는 애플리케이션이 프록시 환경 변수를 무시하더라도 인터넷에 직접 도달할 수 없음을 의미합니다.
프록시의 CA 인증서는 Docker 볼륨을 통해 공유되며 시작 시 에이전트 시스템 트러스트 스토어에 자동으로 설치됩니다.
일치하는 요청의 경우, 정책은 프록시에게 호스트 측 비밀 파일에서 HTTP 헤더를 주입하도록 지시할 수도 있습니다. 이 비밀 디렉터리는 프록시에만 마운트되며, 에이전트 컨테이너는 원본 토큰이나 비밀 마운트를 볼 수 없습니다.
따라서 에이전트가 이러한 가드레일과 싸우는 턴을 낭비하지 않도록, 해당 이미지는 프록시/방화벽 모델을 설명하고 유효한 허용 목록(effective allowlist)을 어디서 읽어야 하는지(/run/agentbox/policy.yaml), 그리고 요청이 차단되었을 때 무엇을 해야 하는지를 설명하는 operating-in-agent-sandbox 스킬을 포함합니다. 이 스킬은 /usr/local/share/agent-sandbox/skills/에 내장되어 있으며, 시작 시 에이전트의 스킬 검색 디렉터리(~/.agents/skills/는 크로스-에이전트 컨벤션용, ~/.claude/skills/는 Claude용)로 심볼릭 링크됩니다. 따라서 모든 샌드박스가 프로젝트별 설정 없이 이 스킬을 갖게 됩니다.
기본 이미지에는 GitHub CLI도 포함되어 있습니다. 정책에서 리포지토리 범위의 api 표면(surface)을 사용하면, 에이전트는 토큰이 호스트에 남아 있는 상태로 이슈와 풀 리퀘스트를 읽고 쓸 때 gh api repos/{owner}/{repo}/...를 사용합니다. 이 스킬은 검증된 명령어를 전달합니다. docs/github.md를 참조하세요.
프록시는 또한 에이전트가 읽을 수 있도록 실시간 허용 목록(live allowlist)을 /run/agentbox/policy.yaml에 작성합니다. 이것은 보안 취약점이 아니라 편의 기능입니다: 이는 읽기 전용 사본이며 (에이전트는 이를 수정할 수 없고, 수정하더라도 아무것도 변경되지 않습니다 — 강제 적용은 프록시에서 이루어지므로), 호스트/스키마/메서드/경로/쿼리 규칙으로만 **정제(sanitized)**되었으며, 자격 증명 셔임(credential-shim) 자료와 요청 재작성 변환(request-rewriting transforms)은 제거되었습니다. 이는 에이전트가 어떤 호스트가 응답하는지 탐색하여 이미 배울 수 있는 것을 노출하지 않습니다. 단지 왕복 횟수를 절약해 줄 뿐입니다. 네트워크 정책은 여전히 호스트에서만(agentbox edit policy) 변경할 수 있으며, 컨테이너 내부에서는 절대 변경할 수 없습니다.
네트워크 정책은 프로젝트의 .agent-sandbox/policy/ 디렉터리에 있습니다.
정책 파일을 편집하려면:
agentbox edit policy
이 명령어는 사용자 레이어 파일(.agent-sandbox/policy/user.policy.yaml)을 에디터에서 열어주며, 이 파일은 에이전트 전환 시에도 유지되고 기본 에이전트 정책 위에 적용됩니다. 프록시가 실행되는 동안 활성 정책 변경 사항을 저장하면, agentbox가 프록시 정책을 핫 리로드(hot-reloads)합니다.
예시 정책:
공개 패키지 레지스트리인 PyPI 같은 곳은 기본적으로 허용되지 않습니다. 만약 필요하다면, 사용자 정책이나 에이전트별 정책에 명시적으로 추가해야 합니다. 가능하다면 사설 미러(private mirror)나 프록시를 사용하는 것이 좋습니다.
GitHub 역시 git과 api 표면을 독립적으로 구성하여 리포지토리 단위로 제한할 수 있습니다:
services:
- name: github
merge_mode: replace
...
프록시 측 자격 증명 주입(credential injection)이 필요한 사설 레포의 경우, git.auth.secret을 추가하십시오. 푸시 접근(push access)의 경우, git.access: readwrite를 사용하고 git-askpass 클라이언트 쉼(shim)을 추가하여 Git이 요청에 도달하기 전에 프록시가 가짜 자격 증명을 대체할 수 있도록 비대화형(non-interactively)으로 실행되게 합니다:
services:
- name: github
merge_mode: replace
...
호스트 측 비밀 설정에 대해서는 컨테이너 내부에서 GitHub Git 사용하기를 참조하십시오.
정책 파일을 직접 편집하는 경우, 프록시를 재시작하지 않고도 변경 사항을 적용할 수 있습니다:
agentbox proxy reload
agentbox proxy logs
단일 에이전트에만 적용되는 사용자 정의 설정을 하려면, .agent-sandbox/policy/user.agent.<agent>.policy.yaml 파일을 편집할 수 있습니다. 예를 들어, Claude Code를 사용할 때만 호스트 또는 요청 규칙을 추가하려면 user.agent.claude.policy.yaml 파일에 추가하십시오.
전체 정책 형식 참조는 docs/policy/schema.md에서, 요청 인식 규칙(request-aware rules) 사용법은 docs/upgrades/m14-request-aware-rules.md에서, GitHub API 표면 및 이로 인해 발생한 두 가지 정책 동작 변경 사항에 대해서는 docs/upgrades/m17-github-api-access.md를 참조하십시오.
컨테이너 내부에서 사설 GitHub 레포를 클론(clone), 페치(fetch), 또는 푸시하는 권장 방법은 프록시가 자격 증명을 주입하도록 하는 것입니다. 토큰은 호스트 측 비밀 디렉토리에 저장되며, 컨테이너의 파일 시스템이나 Docker 볼륨에는 절대 저장되지 않습니다.
agentbox init을 실행하면 기본 비밀(secret) 디렉터리가 생성됩니다. AGENTBOX_SECRET_DIR 환경 변수를 다른 곳으로 지정하려면, 해당 디렉터리를 직접 생성해야 합니다. 그런 다음 토큰 파일을 추가하세요:
mkdir -p "${AGENTBOX_SECRET_DIR:-${HOME}/.config/agent-sandbox/secrets}"
chmod 700 "${AGENTBOX_SECRET_DIR:-${HOME}/.config/agent-sandbox/secrets}"
printf '%s' "ghp_examplevalue" \
...
정책을 변경한 후에는 agentbox proxy reload를 실행하세요. 정책이 client_shim을 사용하는 경우, Git이 생성된 askpass 환경을 인식할 수 있도록 새로운 agentbox exec 셸을 여세요.
gh api를 위한 리포지토리 범위 GitHub API 접근: 토큰, 정책 및 제한