이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

샌드박스 모드

상태: 활성 범위: 현재 상태 최종 검토: 2026-08-23 담당: ax-code 런타임

AX Code에는 AI 에이전트가 시스템에서 할 수 있는 일을 제한하는 내장 실행 샌드박스가 있습니다. 기본값으로 AX Code는 샌드박스를 끈 전체 접근으로 시작하므로, 파일 시스템 쓰기와 네트워크 접근은 제한되지 않습니다. 신뢰할 수 없는 저장소를 다루거나 무인 작업을 실행하기 전에 workspace-write 또는 read-only을 켭니다.

보안 경고: full-access는 보안 경계가 아닙니다. 에이전트는 워크스페이스 밖의 파일을 수정하고, .git/와 .ax-code/를 쓰며, 제한 없는 셸 명령을 실행하고, 네트워크에 접근할 수 있습니다.

빠른 시작

TUI에서 샌드박스를 전환합니다.

• 프롬프트에 /sandbox를 입력하거나
• Ctrl+P를 누르고 “sandbox”를 검색합니다

상태 표시줄이 현재 상태를 보여 줍니다.

• sandbox on(녹색) — 에이전트가 워크스페이스 안에 갇힙니다
• sandbox off(빨간색) — 제한이 없습니다

설정은 세션을 넘어 ax-code.json에 유지됩니다.

바뀌는 것

구성

기준 원천

이 페이지는 사용자가 보는 동작을 요약합니다. 동작이 바뀌면 문서를 다음과 대조하여 확인합니다.

• packages/ax-code/src/isolation/index.ts에서 모드 결정, 보호 경로, 네트워크 검사, 쓰기 검사, bash 검사, IsolationDeniedError을 확인합니다.
• 구성 형태, 기본값, 설명은 packages/ax-code/src/config/schema.ts를 보십시오.
• 런타임 전환 동작과 지속성은 packages/ax-code/src/server/routes/isolation.ts를 보십시오.
• 기대하는 강제 동작은 packages/ax-code/test/isolation/isolation.test.ts와 packages/ax-code/test/tool/bash.test.ts를 보십시오.

루트 README에 중복되는 주장은 짧게 두고, 세부 사항은 이 페이지로 연결합니다.

TUI에서 전환

/sandbox 또는 명령 팔레트(Ctrl+P → “Turn sandbox on/off”)를 사용합니다. 변경은 즉시 적용되고 프로젝트의 ax-code.json에 저장됩니다.

CLI 플래그

ax-code --sandbox workspace-write   # sandbox on
ax-code --sandbox full-access       # sandbox off
ax-code --sandbox read-only         # strictest: blocks all mutations

환경 변수

AX_CODE_ISOLATION_MODE=workspace-write ax-code

구성 파일

ax-code.json에서 다음을 둡니다.

{
  "isolation": {
    "mode": "workspace-write",
    "network": false
  }
}

우선순위

CLI 플래그 > 환경 변수 > 구성 파일 > 기본값(full-access)

CLI나 환경 변수 덮어쓰기가 활성일 때 TUI는 그 유효 모드를 보고합니다. /sandbox 전환은 프로젝트 기본 설정을 저장할 수 있지만, 더 높은 우선순위의 덮어쓰기는 제거할 때까지(보통 다시 시작할 때까지) 활성으로 남습니다.

격리 모드

보호 경로

workspace-write 모드에서는 다음 경로가 항상 쓰기 보호됩니다.

• .git/ — 실수로 git 상태가 손상되는 것을 막습니다
• .ax-code/ — 구성과 플러그인 변조를 막습니다

구성에 사용자 지정 보호 경로를 추가합니다.

{
  "isolation": {
    "mode": "workspace-write",
    "protected": ["secrets", "credentials"]
  }
}

네트워크 접근

네트워크는 workspace-write 모드와 read-only 모드에서 기본적으로 꺼집니다. 영향을 받는 도구는 다음과 같습니다.

• webfetch — 차단
• websearch — 차단
• codesearch — 차단
• bash — 네트워크 전용 클라이언트(curl, wget, nc/ncat/netcat, telnet, ftp, tftp, scp, sftp, dig, nslookup, host)가 차단됩니다

제한: bash의 네트워크 차단은 애플리케이션 계층이며, 위에 있는 전용 네트워크 클라이언트를 다룹니다. 오프라인에서도 동작하는 이중 용도 도구(git, npm/pnpm/yarn, pip, go, python/node 같은 언어 인터프리터)는 가로채지 않습니다. 오프라인 호출을 정적으로 구분할 수 없고, 막으면 흔한 작업 흐름이 깨지기 때문입니다. 진짜로 빠짐없는 네트워크 격리는 OS 수준 제어가 필요하며, 이 샌드박스는 그것을 제공하지 않습니다. 거부된 클라이언트가 쓰이면 에이전트가 일회성 상향을 묻습니다.

쓰기 제한을 유지한 채 네트워크를 허용하려면 다음을 사용합니다.

{
  "isolation": {
    "mode": "workspace-write",
    "network": true
  }
}

격리 백엔드(앱 대 OS)

macOS: sandbox-exec를 통한 Seatbelt 프로필(쓰기는 워크스페이스와 워크트리로 제한되고, network: false일 때 네트워크가 거부됩니다).
Linux: 설치되어 있으면 bubblewrap(bwrap). 네트워크가 꺼지면 --unshare-net이며, 워크스페이스는 읽기/쓰기로 바인드 마운트됩니다.
Windows: 현재는 앱 계층만 해당합니다.

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

위협 모델은 SECURITY.md를 보십시오.

저장소가 제어하는 권한과 훅

프로젝트 파일은 기본적으로 신뢰하지 않습니다. ax-code.json, .ax-code/policy.json의 권한 규칙과 프로젝트 에이전트 또는 모드 정의는 deny로 접근을 더 조일 수 있지만, 저장소가 제어하는 allow/ask 허가는 무시됩니다. 프로젝트 명령은 셸 확장을 켤 수 없습니다. .ax-code/hooks.json, .ax-code/plugin/, 프로젝트에 구성된 플러그인은 실행되지 않습니다.

신뢰하지 않는 프로젝트 구성은 사용자 지정 셸, 실행 가능한 LSP나 포매터, 공급자 패키지나 API 엔드포인트, 공급자 자격 증명 환경 변수, 외부 스킬 원천, 워크트리 밖의 지침 경로도 선택할 수 없습니다. 안전한 상대 지침 경로와, 실행 파일이 아닌 내장 덮어쓰기는 계속 사용할 수 있습니다. MCP 서버는 MCP 통합에 설명된, 지문으로 구분하는 별도의 승인 흐름을 사용합니다.

저장소가 제어하는 구성을 검토한 뒤, 사용자는 현재 프로세스에 대해 저장소 밖에서 선택할 수 있습니다.

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

환경 변수만 쓰는 스위치이므로, 체크아웃이 스스로를 신뢰된다고 선언할 수 없습니다.

강제가 동작하는 방식

샌드박스 강제는 항상 애플리케이션 계층이며, 도구를 호출할 때마다 검사합니다. backend이 os 또는 auto이고 플랫폼이 지원하면, bash는 추가로 커널 샌드박스에 감쌉니다.

도구가 격리를 위반하면, 무엇이 왜 차단되었는지를 설명하는 명확한 메시지와 함께 IsolationDeniedError를 던집니다.