테마
Local command sandbox
목표
로컬 명령 샌드박스를 켜고 sandbox.json으로 네트워크 모드를 설정해, 에이전트가 실행하는 셸 명령을 OS 수준 경계 안에서 제한하는 방법을 파악합니다.
개념
Local command sandbox는 Kiro 에이전트 harness가 실행하는 셸 명령 둘레에 운영체제 경계를 추가합니다. 에이전트 자체를 샌드박스로 옮기지 않으면서, 각 명령과 자식 프로세스가 접근할 수 있는 범위를 제한합니다.
샌드박스가 다루는 것:
- 에이전트가 실행하는 터미널 명령과 그 명령이 시작한 모든 자식 프로세스
- MCP wrapping을 켰을 때의 stdio MCP 서버 프로세스
샌드박스 바깥:
- 에이전트 harness와 모델과의 대화
- 내장 파일 도구(접근 범위는 permission 규칙이 통제)
- Remote HTTP·SSE MCP 서버(네트워크 트래픽이 샌드박스 규칙을 따르지 않음)
💡 샌드박스는 명령이 할 수 있는 일을 줄여줄 뿐, 완전한 격리를 보장하지 않습니다. 제안된 명령을 계속 검토하고, 절대 실행되면 안 되는 작업에는
deny규칙을 유지하세요.
활용
Local command sandbox는 Kiro IDE 1.3 이상, Kiro CLI 2.31 이상의 로컬 V3 세션에서 사용할 수 있습니다. 기본적으로 꺼져 있습니다.
| 플랫폼 | 요구 사항 |
|---|---|
| macOS | 없음. 내장 Seatbelt 샌드박스를 sandbox-exec로 사용 |
| Linux | PATH에 Bubblewrap(bwrap). Kiro가 설치하지 않음. COMMON_DEPENDENCIES와 allowed host가 있는 DEFAULT_BLOCKED에는 socat도 필요 |
| Windows | COMMON_DEPENDENCIES·DEFAULT_ALLOWED 사용 전 1회 관리자 설정. IDE가 안내하며, CLI는 /sandbox setup. DEFAULT_BLOCKED는 설정 전에도 동작 |
설정
두 클라이언트 모두 global·project 수준에서 sandbox.json을 읽습니다.
| Scope | 경로 | 용도 |
|---|---|---|
| Global | Kiro IDE: ~/.kiro/settings/sandbox.json. Kiro CLI: $KIRO_HOME/settings/sandbox.json(설정 시), 아니면 ~/.kiro/settings/sandbox.json | 프로젝트 전반의 기본 정책 |
| Project | <workspace-root>/.kiro/settings/sandbox.json | 한 저장소에 샌드박스를 켜거나 더 조이기 |
Keys
| Key | 필수 | 값 | 기본값 |
|---|---|---|---|
enabled | 예 | true, false | |
networkAccess | 아니오 | DEFAULT_BLOCKED, COMMON_DEPENDENCIES, DEFAULT_ALLOWED | DEFAULT_BLOCKED |
mcpSandboxing | 아니오 | true, false | false |
networkAccess 값은 대소문자를 구분합니다. 알 수 없는 key는 무시됩니다.
켜는 예시:
json
{
"enabled": true,
"networkAccess": "COMMON_DEPENDENCIES"
}global 정책이 활성이면 project 파일은 더 조이기만 할 수 있습니다. project가 enabled를 false로 하거나, 더 개방적인 네트워크 모드를 고르거나, global로 켠 MCP wrapping을 끌 수는 없습니다. 복제한 저장소가 자신의 project 파일로 네트워크를 열거나 활성 global 정책을 끌 수 없다는 뜻입니다.
네트워크 모드
networkAccess는 샌드박스 명령의 아웃바운드 네트워크 접근 시작점을 정하고, sandbox_network permission 규칙이 이를 다듬습니다.
| 모드 | 아웃바운드 네트워크 |
|---|---|
DEFAULT_BLOCKED | sandbox_network 규칙으로 허용된 host를 제외하고 차단. 기본값 |
COMMON_DEPENDENCIES | 흔한 패키지·소스·빌드·컨테이너 서비스에 접근 가능. 그 외 host는 규칙이 없으면 차단 |
DEFAULT_ALLOWED | 개방. 모든 host에 접근 가능. 이 모드에서는 sandbox_network deny 규칙에 의존하지 말 것 |
특정 host 허용
sandbox_network은 permission capability입니다. host 규칙은 순서대로 적용되며 처음 매치된 규칙이 결정합니다 — deny가 항상 이기는 다른 capability와 다릅니다. 그러므로 구체적인 host를, 같이 매치되는 더 넓은 wildcard보다 앞에 두어야 합니다. 패턴은 대소문자를 구분하지 않고, 정확한 host 이름과 *.suffix wildcard를 지원합니다.
yaml
# ~/.kiro/settings/permissions.yaml
rules:
- capability: sandbox_network
match: ['packages.internal.example.com']
effect: allow
# Keep this rule before the wildcard below.
- capability: sandbox_network
match: ['uploads.example-corp.net']
effect: deny
- capability: sandbox_network
match: ['*.example-corp.net']
effect: allowsandbox_network은 all 메타 capability에 포함되지 않습니다. capability: all, effect: allow로도 샌드박스 네트워크가 열리지 않습니다.
해볼 것
💡 연습용 프로젝트에서 수행하고, macOS는 별도 설치 없이 바로 켤 수 있습니다.
1단계: 샌드박스 켜기
CLI 로컬 V3 세션에서 /sandbox on으로 global 샌드박스를 켜거나, /sandbox로 설정 패널을 엽니다. IDE라면 상태 표시줄에서 Command sandbox를 선택해 열리는 설정 파일에서 enabled를 true로 바꾸고 네트워크 모드를 고른 뒤 저장합니다. 상태가 Applying 뒤 Active로 바뀌는지 확인합니다.
2단계: 네트워크 모드 바꿔 보기
/sandbox network로 DEFAULT_BLOCKED를 선택한 뒤, 에이전트에 외부 host로의 접근이 필요한 안전한 명령을 시켜 차단되는지 관찰합니다. 그다음 COMMON_DEPENDENCIES로 바꿔 일반 설치·빌드가 통하는지 비교합니다.
3단계: 끄기
/sandbox off로 global 샌드박스를 끕니다. 변경은 재시작 없이 실행 중인 세션에 적용됩니다.
더 알아보기
- Local command sandbox — autonomous mode, headless
--sandbox, MCP wrapping, 오류 복구 포함 - Permissions —
sandbox_network·fs_read·fs_write규칙 - Kiro 동작 원리 — 샌드박스가 붙는 에이전트 harness
출처: kiro.dev 공식 문서 "Local command sandbox" (2026-10-26 확인).