컨테이너 없이 OS 수준에서 임의의 프로세스에 대한 파일시스템 및 네트워크 제한을 적용하는 경량 샌드박싱 도구입니다.
컨테이너 없이 OS 수준에서 임의의 프로세스에 파일 시스템 및 네트워크 제한을 적용하기 위한 경량 샌드박싱 도구입니다.
srt는 네이티브 OS 샌드박싱 프리미티브(macOS에서는 sandbox-exec, Linux에서는 bubblewrap)와 프록시 기반 네트워크 필터링을 사용합니다. 에이전트, 로컬 MCP 서버, bash 명령 및 임의의 프로세스의 동작을 샌드박싱하는 데 사용할 수 있습니다.
베타 리서치 프리뷰
Sandbox Runtime은 더 안전한 AI 에이전트를 구현하기 위해 Claude Code용으로 개발된 리서치 프리뷰입니다. 더 광범위한 생태계가 보다 안전한 에이전틱 시스템을 구축할 수 있도록 돕기 위해 초기 오픈 소스 프리뷰로 공개되었습니다. 초기 리서치 프리뷰인 만큼 API와 구성 형식은 변경될 수 있습니다. AI 에이전트를 기본적으로 더 안전하게 만들기 위한 피드백과 기여를 환영합니다!
npm install -g @anthropic-ai/sandbox-runtime
# Network restrictions
$ srt "curl anthropic.com"
Running: curl anthropic.com
<html>...</html> # Request succeeds
$ srt "curl example.com"
Running: curl example.com
Connection blocked by network allowlist # Request blocked
# Filesystem restrictions
$ srt "cat README.md"
Running: cat README.md
# Anthropic Sandb... # Current directory access allowed
$ srt "cat ~/.ssh/id_rsa"
Running: cat ~/.ssh/id_rsa
cat: /Users/ollie/.ssh/id_rsa: Operation not permitted # Specific file blocked
이 패키지는 CLI 도구와 라이브러리로 모두 사용할 수 있는 독립형 샌드박스 구현을 제공합니다. 일반적인 개발자 사용 사례에 맞춘 기본적으로 안전한(secure-by-default) 철학을 바탕으로 설계되었습니다. 프로세스는 최소한의 접근 권한으로 시작하며, 필요한 부분만 명시적으로 열어줍니다.
주요 기능:
주요 사용 사례 중 하나는 Model Context Protocol(MCP) 서버를 샌드박싱하여 해당 서버의 기능을 제한하는 것입니다. 예를 들어, 파일시스템 MCP 서버를 샌드박싱하려면 다음과 같이 합니다:
샌드박싱 없이 (.mcp.json):
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem"]
}
}
}
샌드박싱 사용 시 (.mcp.json):
{
"mcpServers": {
"filesystem": {
"command": "srt",
"args": ["npx", "-y", "@modelcontextprotocol/server-filesystem"]
}
}
}
그런 다음 ~/.srt-settings.json에서 제한 사항을 구성합니다:
{
"filesystem": {
"denyRead": [],
"allowWrite": ["."],
"denyWrite": ["~/sensitive-folder"]
},
"network": {
"allowedDomains": [],
"deniedDomains": []
}
}
이제 MCP 서버는 거부된 경로에 쓰기가 차단됩니다:
> Write a file to ~/sensitive-folder
✗ Error: EPERM: operation not permitted, open '/Users/ollie/sensitive-folder/test.txt'
샌드박스는 OS 수준의 기본 요소를 사용하여 전체 프로세스 트리에 적용되는 제한을 시행합니다:
sandbox-exec를 사용합니다srt-sandbox 로컬 사용자 계정으로 샌드박스된 프로세스를 실행하며, 해당 계정의 SID를 키로 하는 Windows Filtering Platform 이그레스 펜스, 쓰기 제한 토큰, 그리고 작업 트리에 대한 명시적 ACE를 사용합니다0d1c612947c798aef48e6ab4beb7e8544da9d41a-4096x2305
효과적인 샌드박싱을 위해서는 파일 시스템 격리와 네트워크 격리 모두 필요합니다. 파일 격리가 없으면 침해된 프로세스가 SSH 키나 기타 민감한 파일을 유출할 수 있습니다. 네트워크 격리가 없으면 프로세스가 샌드박스를 탈출하여 무제한 네트워크 액세스를 얻을 수 있습니다.
파일 시스템 격리는 읽기 및 쓰기 제한을 시행합니다:
/Users)을 거부한 다음 그 안의 특정 경로(예: .)를 다시 허용할 수 있습니다. allowRead는 denyRead보다 우선합니다 — 이는 denyWrite가 allowWrite보다 우선하는 쓰기와는 반대입니다. allowRead 영역 내부에 있으면서 그보다 더 구체적인 denyRead 항목(예: allowRead: ["."]와 함께 denyRead: ["**/.env"] 또는 ["./secrets"])은 여전히 거부된 상태로 유지됩니다.., /tmp)를 명시적으로 허용해야 합니다. 빈 허용 목록은 쓰기 액세스가 없음을 의미합니다.네트워크 격리 (허용 전용 패턴): 기본적으로 모든 네트워크 액세스는 거부됩니다. 도메인을 명시적으로 허용해야 합니다. 빈 allowedDomains 목록은 네트워크 액세스가 없음을 의미합니다. 네트워크 트래픽은 호스트에서 실행되는 프록시 서버를 통해 라우팅됩니다:
Linux: 요청은 Unix 도메인 소켓을 통해 파일 시스템을 경유하여 라우팅됩니다. 샌드박스된 프로세스의 네트워크 네임스페이스가 완전히 제거되므로, 모든 네트워크 트래픽은 호스트에서 실행되는 프록시(샌드박스에 바인드 마운트된 Unix 소켓에서 수신)를 통해야 합니다
macOS: Seatbelt 프로필은 특정 localhost 포트로의 통신만 허용합니다. 프록시가 이 포트에서 수신하여 모든 네트워크 액세스를 위한 제어된 채널을 만듭니다
Windows: 머신 전체 WFP 필터 세트가 srt-sandbox 계정으로 실행되는 프로세스가 만드는 아웃바운드 연결을 차단하며, 프록시 포트 범위로의 루프백은 예외입니다. 프록시는 해당 범위 내에서 수신하여 모든 네트워크 액세스를 위한 제어된 채널을 만듭니다. 이 필터는 소켓을 생성하기 전에 스레드에 다른 토큰을 설정하는 샌드박스된 프로세스를 따르지 않으며, 시스템 서비스가 대신 전달하는 트래픽도 따르지 않습니다. Windows 알려진 제한 사항을 참조하십시오
HTTP/HTTPS(HTTP 프록시 경유)와 기타 TCP 트래픽(SOCKS5 프록시 경유) 모두 이러한 프록시에 의해 중개되며, 프록시는 도메인 허용 목록과 거부 목록을 시행합니다.
Claude Code의 샌드박싱에 대한 자세한 내용은 다음을 참조하십시오:
src/
├── index.ts # Library exports
├── cli.ts # CLI entrypoint (srt command)
├── utils/ # Shared utilities
│ ├── debug.ts # Debug logging
│ ├── settings.ts # Settings reader (permissions + sandbox config)
│ ├── platform.ts # Platform detection
│ └── exec.ts # Command execution utilities
└── sandbox/ # Sandbox implementation
├── sandbox-manager.ts # Main sandbox manager
├── sandbox-schemas.ts # Zod schemas for validation
├── sandbox-violation-store.ts # Violation tracking
├── sandbox-utils.ts # Shared sandbox utilities
├── http-proxy.ts # HTTP/HTTPS proxy for network filtering
├── socks-proxy.ts # SOCKS5 proxy for network filtering
├── linux-sandbox-utils.ts # Linux bubblewrap sandboxing
├── macos-sandbox-utils.ts # macOS sandbox-exec sandboxing
└── windows-sandbox-utils.ts # Windows srt-win sandboxing
srt 명령(Anthropic Sandbox Runtime)은 모든 명령을 보안 경계로 감쌉니다:
# Run a command in the sandbox
srt echo "hello world"
# With debug logging
srt --debug curl https://example.com
# Specify custom settings file
srt --settings /path/to/srt-settings.json npm install
설정 파일은 선택 사항입니다 — ~/.srt-settings.json에 파일이 없으면 srt는 내장 기본값으로 실행됩니다: 네트워크 접근 없음, 기본 쓰기 경로 외부에 쓰기 없음, 읽기는 제한 없음. 파일이 있지만 비어 있거나, 읽을 수 없거나, 검증을 통과하지 못하면 오류입니다: srt는 그렇게 알리고 기본값으로 폴백하지 않고 종료합니다. 기본값은 더 약한 설정이 아니라 다른 설정이기 때문입니다 — 폴백하면 파일의 denyRead, allowRead 및 자격 증명 규칙을 비롯해 파일이 지정한 모든 것이 사라집니다. --settings로 지정한 파일도 마찬가지이며, 이 파일 역시 존재해야 합니다.
--control-fd--control-fd <fd>는 호출자가 이미 열어 둔 디스크립터에서 설정 업데이트를 읽으며, 설정 파일과 같은 형태의 JSON 객체를 한 줄에 하나씩 읽습니다. 각 줄은 전체 설정을 대체하며 동일한 스키마로 검증되므로, 한 줄은 패치가 아니라 완전한 설정입니다: network와 filesystem은 필수이며, 줄에서 생략된 키는 기본값으로 돌아갑니다.
# fd 3 is the read end of a pipe the caller writes lines to
srt --control-fd 3 -- npm test
실행 중인 명령에 대해 허용된 라인이 적용되면 바뀌는 사항:
network.allowedDomains, deniedDomains(deniedDomainReasons 포함) 및 deniedResolvedAddresses — 은 모든 플랫폼에서 다음 연결 시점에 적용됩니다. 프록시는 요청마다 이 목록을 참조하며, 확인된 주소 검사도 같은 라인에서 다시 구성됩니다. 요청마다 읽는 network.mitmProxy와 network.tlsTerminate.excludeDomains도 마찬가지입니다.credentials.sigv4는 srt가 credentials 블록과 함께 시작된 경우 다음 요청 시점에 적용됩니다. 서명 훅은 그때만 설치되며, 정책을 캡처하지 않고 요청마다 읽습니다.network.parentProxy와 TLS 종료 여부를 캡처했습니다.filesystem.*과 credentials.files를 합친 것)이 시작 시 적용된 집합과 다른 라인을 감지하고, SRT_DEBUG에서만 이를 알립니다. ACL 부여는 세션 전체에 적용되므로 시작 시 적용된 집합이 계속 유효합니다. 라인의 나머지 부분은 위와 같이 적용됩니다.srt가 채널을 읽는 방식과 거부하는 대상: