코딩 에이전트를 위한 외부 샌드박스
TMThttps://blog.primeradiant.com/external-sandboxes-for-coding-agents/
우리는 이 방식을 외부 샌드박스라고 부릅니다.
샌드박스 프로토타입을 세 가지 만들었습니다. 하나는 Node.js와 WebAssembly를, 하나는 Apple Containers를, 하나는 Microsoft의 Quicksand와 QEMU를 사용합니다. 세 구현 모두 같은 프로토콜을 따릅니다. Claude Code, Codex, Pi가 각 샌드박스에서 코드를 실행하도록 설정하는 방법도 함께 제공합니다.
가장 간단한 예제는 npx 명령 두 개로 실행할 수 있습니다.
명령 두 개로 실행해 보기
프로젝트 디렉터리로 이동한 뒤 npx로 새 샌드박스를 시작합니다. 이 명령은 Alpine Linux를 내려받아 v86에서 실행합니다. v86은 WebAssembly로 컴파일한 x86 에뮬레이터로, Node.js에서 동작합니다. Node.js 22.19 이상이면 실행할 수 있습니다.
npx --yes external-sandbox-v86 \
--preserve-paths --mount-rw "project=$PWD"같은 디렉터리에서 터미널을 하나 더 열고, 다음과 같이 코딩 에이전트 Pi를 시작합니다. Pi를 처음 사용한다면 에이전트 안에서 /login을 실행해 모델에 접근할 수 있게 해야 합니다.
npx --yes @earendil-works/pi-coding-agent \
-e npm:external-sandbox-pi --no-builtin-tools \
--sandbox-url http://127.0.0.1:8686Pi에서 !uname -a를 실행하면 아래와 같은 결과가 나옵니다. 명령이 Alpine Linux에서 실행됐음을 확인할 수 있습니다.
Linux (none) 6.12.114-0-virt #1-Alpine SMP PREEMPT_DYNAMIC 2026-10-21 12:19:03 i686 Linux이제 Pi는 프로젝트 폴더에서 파일을 읽고 쓸 수 있고, 샌드박스에서 명령을 실행할 수 있습니다. 호스트 컴퓨터에서 접근할 수 있는 범위는 이 프로젝트 폴더로 제한됩니다.
Claude Code와 Codex도 설정을 조금 더 하면 사용할 수 있습니다. 구체적인 방법은 아래에서 설명합니다.
외부 샌드박스로 할 수 있는 일
- 에이전트는 Mac에서 실행합니다. Pi, Claude Code, Codex 자체는 평소처럼 Mac에서 실행합니다. 에이전트가 내리는 명령은 샌드박스로 보냅니다.
- 샌드박스는 마운트한 폴더에만 접근합니다. 명령이 접근할 수 있는 폴더와 각 폴더의 읽기 전용 또는 읽기·쓰기 권한을 사용자가 정합니다.
- 네트워크는 허용한 호스트에만 연결합니다. 샌드박스는 기본적으로 외부와 통신할 수 없습니다. 시작할 때
--proxy옵션을 주면 HTTP/HTTPS 프록시를 통해 허용한 호스트에만 접근할 수 있습니다. - API 키를 에이전트에 노출하지 않습니다. 프록시는 인증 정보 치환을 지원합니다. 특정 호스트로 보내는 요청에 API 키를 추가하면서, 키 자체는 샌드박스 외부에 보관해 요청을 보낸 에이전트가 볼 수 없게 합니다.
- 웹 화면에서 규칙을 바꿀 수 있습니다. 샌드박스 웹 화면에서 브라우저 터미널을 열고, 프록시 설정을 바꾸고, 네트워크 요청 기록을 확인할 수 있습니다.
- 에이전트와 샌드박스를 자유롭게 조합할 수 있습니다. 샌드박스 세 가지가 같은 프로토콜을 구현하므로 원하는 에이전트와 조합해 사용할 수 있습니다.
구성도
Mac에서 Claude Code, Codex, Pi 등의 코딩 에이전트가 localhost의 샌드박스 서버에 명령을 보내면, 서버가 Linux 가상 머신(VM)에서 명령을 실행합니다. VM은 마운트한 폴더를 통해 파일을 주고받으며, 프록시의 허용 목록에 있는 인터넷 호스트에 접근할 수 있습니다. VM 외부로 통하는 경로는 이 두 가지뿐입니다.
외부 샌드박스를 쓰는 이유
코딩 에이전트도 실수할 수 있습니다. 에이전트가 실수하면 읽거나 수정할 권한이 있는 데이터가 손상되거나 유출될 수 있습니다.
이상적으로는 에이전트가 일으킬 수 있는 피해를 엄격히 제한하는 안전한 환경에서 실행해야 합니다. 현실에서는 많은 사람이 에이전트에 자기 컴퓨터와 외부 네트워크를 마음대로 쓸 권한을 주고 별일 없기를 바랍니다.
에이전트가 하려는 작업을 하나씩 직접 승인하는 방법도 있습니다. 하지만 이렇게 일하면 속도가 답답할 만큼 느려집니다. 판단에 지치는 것도 금방입니다. 결국 무엇을 묻는지 제대로 읽어 볼 여유 없이 무심코 모든 요청을 승인하게 됩니다.
외부 샌드박스 방식에서는 에이전트가 샌드박스 안에서 코드를 실행하고 파일을 수정합니다. 에이전트는 명령을 내리고 코드를 작성해 실행할 수 있고, 사용자는 에이전트가 접근할 수 있는 파일, 환경 변수, 네트워크 연결을 정할 수 있습니다.
Anthropic과 OpenAI 모두 에이전트의 안전성을 높이는 데 많은 노력을 기울였습니다. Claude Code의 자동 모드와 Codex의 자동 검토는 AI가 한 번 더 검사해 작업을 계속해도 안전할지 판단합니다. 두 기능 모두 잘 동작하는 것으로 보입니다.
이 검사는 각 제품에 내장된 기능이며, 개별 작업에 대한 모델의 판단이 정확해야 효과를 냅니다. 샌드박스의 보호는 모델의 판단에 의존하지 않습니다. 더 저렴한 모델이나 로컬에서 실행할 수 있는 모델 등 다른 모델을 써 보고 싶다면 안전을 우선으로 고려해야 합니다. 가벼운 모델은 실수가 더 잦고, 의도적인 프롬프트 인젝션 공격에도 더 쉽게 속습니다.
우리 목표는 코딩 에이전트가 샌드박스에서 작업할 수 있도록 견고하고 믿을 수 있으며 사용하기 쉬운 방식을 찾는 것입니다. 에이전트가 실행하는 명령은 우리가 정한 파일만 읽고 쓸 수 있고, 우리가 허용한 네트워크 요청만 보낼 수 있어야 합니다.
에이전트가 샌드박스를 사용하게 하는 방식 두 가지를 검토했습니다. 첫째는 Fly의 Sprites 같은 시스템처럼 에이전트 자체를 샌드박스 안에서 실행하는 방식입니다. 둘째는 에이전트를 샌드박스 밖에서 실행하고, 명령만 별도의 샌드박스로 보내는 방식입니다.
우리는 두 번째 방식을 택했습니다. 에이전트가 자기 자신이나 직접 실행되는 환경을 수정하는 예기치 않은 동작을 피할 수 있고, 샌드박스의 경계가 명확해져 감사하기도 쉽습니다.
‘외부 샌드박스’에서 외부란 에이전트 바깥을 뜻합니다. 샌드박스와 에이전트는 같은 컴퓨터에서 실행할 수 있습니다.
프로토타입 세 가지
세 프로젝트는 서로 다른 기술로 외부 샌드박스를 구현하며, 같은 프로토콜을 사용해 서로 호환됩니다.
- external-sandbox-v86은 WebAssembly로 실행하는 v86을 이용해 Alpine Linux를 구동하는 Node.js 프로세스입니다. npm 패키지에 샌드박스에서 실행할 Linux 배포판 전체가 들어 있습니다.
- external-sandbox-container는 Linux를 실행하는 Apple Containers를 감싼 Python 프로세스입니다. 컨테이너를 시작하고 프로토콜로 받은 명령을 그 안에서 실행한 뒤, 프로세스를 종료할 때 컨테이너도 종료합니다.
- external-sandbox-quicksand는 Microsoft의 Quicksand를 사용해 QEMU 가상 머신을 구동하는 Python 프로세스입니다. QEMU와 Alpine 이미지가 Python 휠로 제공되므로 따로 설치할 것이 없습니다.
세 시스템은 localhost에서 같은 웹 API를 제공하며, 에이전트마다 이 API에 연결하는 방식이 다릅니다.
- Claude Code는 Bash 도구의 명령만 샌드박스로 보냅니다. 내장 Read와 Edit 도구는 샌드박스 바깥의 호스트에서 실행합니다.
- Codex는 프로세스와 파일 시스템 작업을 샌드박스로 보냅니다. 내장
apply_patch도 여기에 포함됩니다. - Pi는
bash,read,write,edit,grep,find,ls도구의 작업을 샌드박스로 보냅니다.grep과find를 쓰려면 게스트 환경에 ripgrep이 필요하며, 세 샌드박스의 기본 이미지에 모두 포함돼 있습니다.
이 API의 명세와 명세 준수 여부를 검사하는 도구도 만들었습니다. 다른 기술을 사용하더라도 호환되는 샌드박스 서버를 쉽게 만들 수 있습니다.
다른 샌드박스와 에이전트에서 사용하기
v86으로 Alpine을 실행하는 Node.js 서버의 기본 포트는 8686입니다. Python으로 만든 Apple Containers 서버는 8687, Quicksand 서버는 8688을 사용하므로 세 서버를 동시에 실행할 수 있습니다.
v86 서버는 npm에 공개되어 있으며 npx로 실행합니다. Python 서버 두 가지는 external-sandbox-container와 external-sandbox-quicksand라는 이름으로 PyPI에 공개되어 있으며 uvx로 실행합니다.
v86 Node.js 서버는 다음과 같이 시작합니다.
# v86 Alpine Node.js (Node.js 22+)
npx --yes external-sandbox-v86 \
--preserve-paths --mount-rw "project=$PWD"Apple Containers를 사용하려면 다음 명령을 실행합니다.
# Python Apple Containers (Apple silicon Mac with Apple's container CLI)
container system start
uvx external-sandbox-container \
--preserve-paths --mount-rw "project=$PWD"Quicksand를 사용하려면 다음 명령을 실행합니다. 처음에는 Alpine 이미지를 준비해 캐시에 저장하므로 시간이 조금 더 걸립니다.
# Python Quicksand (Apple silicon Mac)
uvx external-sandbox-quicksand \
--preserve-paths --mount-rw "project=$PWD"각 서버는 현재 디렉터리를 /mnt/project에 읽기·쓰기 모드로 마운트합니다. --preserve-paths를 지정했으므로 원래 경로에도 마운트합니다. 덕분에 호스트의 경로를 참조하는 명령을 샌드박스에서도 실행할 수 있습니다. 읽기 전용으로 연결할 폴더는 --mount-ro name=/some/path로 지정합니다. 브라우저에서 서버 포트에 접속하면 터미널을 열고 네트워크 규칙을 관리할 수 있습니다.
Claude Code
Claude Code의 파일 읽기와 편집 도구는 호스트에서 실행됩니다. 마운트 규칙은 Claude의 Bash 명령이 접근할 수 있는 범위를 제한하지만, Claude는 내장 도구로 Mac의 파일을 직접 읽거나 편집할 수 있습니다.
Claude Code를 샌드박스와 연결하려면 external-sandbox 저장소에서 공용 셸 접두사 스크립트를 가져옵니다.
git clone https://github.com/prime-radiant-inc/external-sandbox.git
PREFIX_DIR="$(cd external-sandbox/claude-code && pwd)"그런 다음 서버를 시작했던 프로젝트 디렉터리에서 아래 명령을 실행합니다. 이 예에서는 8686번 포트에서 v86을 실행합니다.
mkdir -p .external-sandbox-claude-tmp
CLAUDE_CODE_SHELL=/bin/bash \
CLAUDE_CODE_TMPDIR="$PWD/.external-sandbox-claude-tmp" \
CLAUDE_CODE_SHELL_PREFIX="$PREFIX_DIR/claude-shell-prefix.sh" \
EXTERNAL_SANDBOX_API_URL=http://127.0.0.1:8686 \
claudev86 서버는 8686번 포트를 사용합니다. Apple Containers는 8687, Quicksand는 8688을 지정합니다. Claude Code가 내부 작업 상태를 기록하는 데 .external-sandbox-claude-tmp 디렉터리를 사용하므로, 이 디렉터리는 쓰기 가능한 마운트 안에 있어야 합니다.
Codex
Codex를 연결하려면 전용 홈 디렉터리를 만들고, 그 안의 environments.toml에서 샌드박스를 가리키도록 설정합니다. 이 예에서는 8686번 포트에서 v86을 실행합니다.
mkdir -p ~/.codex-external-sandbox
cat > ~/.codex-external-sandbox/environments.toml <<'EOF'
default = "external-sandbox"
include_local = false
[[environments]]
id = "external-sandbox"
url = "ws://127.0.0.1:8686/codex"
connect_timeout_sec = 5
initialize_timeout_sec = 10
EOF해당 홈 디렉터리로 한 차례 로그인한 뒤 같은 홈 디렉터리를 사용해 Codex를 시작합니다.
CODEX_HOME=~/.codex-external-sandbox codex login
CODEX_HOME=~/.codex-external-sandbox codex --sandbox danger-full-access \
-c features.shell_snapshot=false \
-c features.unified_exec_tty=false \
--cd "$PWD"danger-full-access를 지정하면 Codex 자체 샌드박스를 외부 샌드박스 안에 겹쳐 적용하지 않습니다. 자동화 테스트는 Codex CLI 0.164.0에서 codex exec와 모의 모델을 사용해 통과했습니다. Codex의 exec-server 프로토콜은 실험 단계이므로 다른 버전에서는 동작을 확인해야 할 수 있습니다.
Pi
Pi를 연결하려면 내장 도구를 끈 상태에서 external-sandbox-pi 확장을 불러옵니다. 서버를 시작했던 프로젝트 디렉터리에서 다음 명령을 실행합니다. 이 예에서는 8688번 포트에서 Quicksand를 실행합니다.
pi -e npm:external-sandbox-pi --no-builtin-tools \
--sandbox-url http://127.0.0.1:8688-e npm:은 이번 실행에 한해 확장을 내려받습니다. --no-builtin-tools를 지정하면 확장을 불러오는 데 실패해도 호스트 컴퓨터에서 실행될 도구가 없습니다. 이 확장은 Pi 1.5 이상이 필요합니다. 연결되면 Pi 상태 표시줄에 Sandbox: ...가 표시됩니다.
네트워크 접근 제어
세 샌드박스 구현은 기본적으로 외부 네트워크에 접근할 수 없습니다. 이 기본 설정은 버그나 프롬프트 인젝션 공격으로 비공개 데이터가 외부에 유출될 위험을 막아 줍니다. 이런 위험은 치명적인 세 가지 조건에서 설명한 바 있습니다.
각 샌드박스는 프록시를 통해 HTTP 및 HTTPS 접근을 허용하도록 설정할 수 있습니다. 프록시는 접근할 수 있는 호스트와 호스트별로 사용할 수 있는 HTTP 메서드를 제한합니다. 이를 통해 특정 호스트에 읽기 전용 접근이나 전체 접근을 허용할 수 있습니다.
프록시를 켜면 샌드박스에 HTTP_PROXY와 HTTPS_PROXY 환경 변수가 설정됩니다. wget 같은 클라이언트는 이 변수를 보고 프록시를 통해 네트워크에 연결합니다. 샌드박스는 프록시의 CA 인증서도 제공하며, SSL_CERT_FILE, REQUESTS_CA_BUNDLE, NODE_EXTRA_CA_CERTS 같은 변수가 이 인증서를 가리키도록 합니다. 이렇게 하면 클라이언트가 HTTPS 사이트에 접근하는 동안 프록시가 트래픽을 검사하고 필터링할 수 있습니다. 코드가 이 설정을 무시하고 직접 연결을 시도하면 연결이 차단됩니다.
--proxy-config 옵션으로 세션에서 허용할 호스트와 메서드가 적힌 파일을 지정할 수 있습니다. 다음은 프록시 설정 파일의 예입니다.
{
"allow": [
{
"origin": "https://pypi.org",
"methods": ["GET", "HEAD"]
},
{
"origin": "https://files.pythonhosted.org",
"methods": ["GET"]
},
{
"origin": "https://api.github.com",
"methods": ["GET"],
"credential": {
"header": "authorization",
"placeholder": "Bearer placeholder-github-token",
"secretEnv": "GITHUB_TOKEN",
"prefix": "Bearer "
}
}
],
"guestEnv": {
"GITHUB_TOKEN": "placeholder-github-token"
}
}HTTP API의 인증 정보 치환
인증 정보 치환을 사용하면 샌드박스 안에서 실행하는 코드가 인증이 필요한 웹 API를 호출할 수 있습니다. 키 자체는 에이전트에 노출하거나 샌드박스에 전달할 필요가 없습니다.
위 예제는 GitHub API에 인증 정보 치환을 설정합니다. 샌드박스는 Bearer placeholder-github-token을 인증 헤더에 넣고 프록시를 통해 https://api.github.com/에 요청을 보낼 수 있습니다. 프록시는 호스트에서 실행되는 샌드박스 서버의 GITHUB_TOKEN 환경 변수 값을 사용해 그 헤더를 바꿉니다. 설정 파일의 guestEnv에는 샌드박스 안의 코드에 제공할 GITHUB_TOKEN 변수를 지정하며, 이 변수에는 자리표시자 값이 들어 있습니다.
덕분에 에이전트는 API 키를 몰라도 인증이 필요한 API를 호출할 수 있습니다. 다만 허용한 호스트가 응답에 인증 정보를 그대로 담아 돌려줄 수 있으므로, 신뢰하는 서비스에만 인증 정보 규칙을 적용하고 메서드와 경로를 좁게 허용하세요.
샌드박스를 다음과 같이 실행하면 프록시에서 GitHub API 토큰을 사용할 수 있습니다.
GITHUB_TOKEN="$(gh auth token)" npx --yes external-sandbox-v86 \
--proxy-config proxy.json \
--preserve-paths --mount-rw "project=$PWD"네트워크 요청을 확인하고 정책 수정하기
아래는 샌드박스의 웹 화면에서 위 네트워크 설정에 따라 요청이 허용되거나 차단되는 모습을 보여 주는 세션입니다. fetch.py는 요청을 한 번 보내고 결과를 출력하는 짧은 스크립트입니다.
external-sandbox-v86의 웹 터미널에서 요청 한 건이 허용되고 두 건이 차단된 모습입니다.
샌드박스 웹 화면의 /proxy 페이지에서는 세션을 실행하는 동안 네트워크 정책을 수정할 수 있습니다. 프록시가 최근에 허용하거나 차단한 요청 기록도 볼 수 있습니다.
네트워크 정책 페이지에 허용된 접속 대상, 정책 JSON 편집기, 최근 프록시 요청 기록이 표시됩니다.
/proxy 페이지는 서버를 --proxy 플래그와 함께 시작했거나, --proxy-config proxy.json으로 초기 설정을 전달한 경우에만 사용할 수 있습니다.
세 샌드박스가 공통으로 사용하는 전체 정책 형식은 프로토콜 명세의 프록시 절에서 확인할 수 있습니다. 더 많은 예제는 v86 프록시 가이드에 있습니다.
에이전트별 샌드박스 연결 방식
코딩 에이전트마다 모든 명령을 지정된 환경에서 실행하도록 설정하는 방식이 다릅니다.
CLAUDE_CODE_SHELL_PREFIX
Claude Code에서는 환경 변수로 실행 방식을 제어합니다. CLAUDE_CODE_SHELL_PREFIX를 설정하면 Claude의 Bash 도구가 모든 명령 앞에 해당 값을 붙여 실행합니다. 예를 들면 다음과 같습니다.
claude-shell-prefix.sh 'uname -m; pwd; printf "hello from Linux\n"'실행 환경이 환경 변수와 세미콜론 등을 포함한 셸 명령 문자열 전체를 처리할 수 있다면, 이 기능으로 원래 내리려던 명령을 받아 원하는 방식으로 실행할 수 있습니다.
codex exec-server
Codex에는 codex exec-server라는 기능이 있습니다. Codex가 하위 프로세스를 시작하고 제어하는 소형 JSON-RPC 서버와 통신할 수 있게 해 줍니다.
OpenAI는 이 서버의 자체 구현을 Codex의 일부로 제공합니다. Codex는 오픈 소스이므로 이 서버가 어떻게 동작하는지 살펴보고 별도의 구현을 만들 수 있습니다.
따라서 이 JSON-RPC 명세를 구현한 서버를 Codex에 지정하면, Codex가 그 서버를 통해 별도의 실행 환경을 제어할 수 있습니다.
앞서 Codex 절에서 보여 준 environments.toml 파일이 Codex에 연결할 서버를 알려 줍니다. 이 파일의 url은 샌드박스의 /codex WebSocket 엔드포인트를 가리킵니다.
Pi 확장
Pi 코딩 에이전트는 확장을 통해 기본 도구를 커스텀 도구로 바꿀 수 있습니다. external-sandbox-pi는 bash, read, write, edit, grep, find, ls 도구를 지정한 샌드박스에서 동작하는 버전으로 교체합니다.
Pi의 !command와 !!command 단축 명령도 샌드박스에서 실행하게 합니다. !command는 명령을 실행해 출력을 대화에 추가합니다. !!command는 명령을 실행하되 출력을 모델에 보내지 않습니다.
pi -e npm:external-sandbox-pi --no-builtin-tools로 시작하면 확장을 불러오지 못해도 Pi가 호스트에서 실행할 도구가 없습니다. 샌드박스에 연결할 수 없으면 도구는 오류를 반환해 명령이 호스트에서 실행되는 일을 막습니다.
명령이 샌드박스로 전달되는지 확인하려면 Pi 안에서 다음을 실행합니다.
!uname -a출력에서 Darwin 대신 Linux를 볼 수 있습니다. 나머지 출력은 실행 중인 샌드박스에 따라 달라집니다.
Pi가 항상 샌드박스와 통신하도록 하려면 다음과 같이 확장을 설치하고 환경 변수를 설정합니다.
pi install npm:external-sandbox-pi
export EXTERNAL_SANDBOX_API_URL=http://127.0.0.1:8686터미널을 새로 열어도 설정이 적용되도록 셸 설정 파일에 export 줄을 추가합니다.
확장을 제거하려면 다음 명령을 실행합니다.
pi remove npm:external-sandbox-pi의견을 들려주세요
이 샌드박스는 아직 실험용 프로토타입입니다. 외부 샌드박스 방식이 어떻게 동작하는지 보여 주지만, 민감한 작업을 맡겨도 될 정도의 보안 감사를 거치지는 않았습니다.
두 가지 제약도 염두에 두세요. 읽기·쓰기 모드로 마운트한 폴더에서는 에이전트가 어떤 파일이든 손상시킬 수 있으므로 버전 관리에 포함하고, 가능하면 읽기 전용으로 마운트하세요. 또한 샌드박스는 Linux에서 실행됩니다. 프로젝트의 node_modules나 .venv 폴더처럼 macOS용으로 빌드한 의존성은 샌드박스 안에서 다시 설치해야 할 수 있습니다.
샌드박스 구현 세 가지와 에이전트 세 가지를 연결해 보면, 이 프로토콜로 다양한 모델, 에이전트, 샌드박스 플랫폼을 조합할 수 있음을 알 수 있습니다. 다른 기술을 기반으로 샌드박스를 만들고 싶다면 명세와 명세 준수 검사 도구부터 살펴보세요.
직접 사용해 보고 개선할 점이 있거나 설계상 결함을 발견했다면 external-sandbox 저장소에 이슈를 남겨 주세요.