logo

샌드박스

샌드박스는 Codex에 컴퓨터 전체에 대한 제한 없는 접근 권한을 주지 않고도 자율적으로 작업하게 하는 경계입니다. Codex가 Codex 앱, IDE 확장, CLI에서 로컬 명령을 실행할 때, 해당 명령은 기본적으로 full access로 실행되지 않고 제한된 환경 안에서 실행됩니다.

이 환경은 Codex가 스스로 무엇을 할 수 있는지 정의합니다. 예를 들어 어떤 파일을 수정할 수 있는지, 명령이 네트워크를 사용할 수 있는지를 정합니다. 작업이 이 경계 안에 머물면 Codex는 확인을 위해 멈추지 않고 계속 진행할 수 있습니다. 경계를 넘어야 할 때는 승인 흐름으로 fallback합니다.

샌드박싱과 승인은 함께 작동하는 서로 다른 제어입니다. 샌드박스는 기술적 경계를 정의하고, 승인 정책은 Codex가 그 경계를 넘기 전에 언제 멈추고 물어야 하는지 결정합니다.

샌드박스가 하는 일

샌드박스는 Codex의 내장 파일 작업뿐 아니라 생성된 명령에도 적용됩니다. Codex가 git, package manager, test runner 같은 도구를 실행하면 해당 명령도 같은 샌드박스 경계를 상속합니다.

Codex는 각 OS에서 플랫폼 네이티브 enforcement를 사용합니다. 구현은 macOS, Linux, WSL2, native Windows마다 다르지만, 원리는 같습니다. agent에게 제한된 작업 공간을 제공해 명확한 한계 안에서 일반 작업을 자율적으로 실행할 수 있게 합니다.

중요한 이유

샌드박스는 승인 피로를 줄입니다. 위험이 낮은 모든 명령을 확인하라고 묻는 대신, Codex가 이미 승인된 경계 안에서 파일을 읽고, 수정하고, 일반 프로젝트 명령을 실행할 수 있습니다.

또한 agentic 작업에 대해 더 명확한 신뢰 모델을 제공합니다. 사용자는 에이전트의 의도만 믿는 것이 아니라, 에이전트가 강제된 제한 안에서 작동한다고 믿는 것입니다. 그래서 Codex가 독립적으로 작업하도록 허용하면서도 언제 멈춰 도움을 요청할지 알 수 있습니다.

시작하기

기본 권한 모드를 사용할 때 Codex는 샌드박싱을 자동으로 적용합니다.

사전 요구 사항

macOS에서는 내장 Seatbelt framework를 사용해 샌드박싱이 바로 작동합니다.

Windows에서는 PowerShell에서 실행할 때 native Windows 샌드박스를 사용하고, WSL2에서 실행할 때는 Linux 샌드박스 구현을 사용합니다.

Linux와 WSL2에서는 먼저 package manager로 bubblewrap을 설치합니다.

Ubuntu/Debian:

sudo apt install bubblewrap

Fedora:

sudo dnf install bubblewrap

Codex는 PATH에서 처음 찾은 bwrap 실행 파일을 사용합니다. bwrap 실행 파일이 없으면 Codex는 번들된 helper로 fallback하지만, 이 helper는 unprivileged user namespace 생성 지원이 필요합니다. 배포판 package가 제공하는 bwrap을 설치하면 설정이 더 안정적입니다.

bwrap이 없거나 helper가 필요한 user namespace를 만들 수 없으면 Codex는 시작 경고를 표시합니다. 이 AppArmor 설정을 제한하는 배포판에서는 제한을 전역으로 비활성화하기보다 bwrap AppArmor profile을 로드해 bwrap이 계속 작동하게 하는 편이 좋습니다.

Ubuntu AppArmor 참고: Ubuntu 25.04에서는 Ubuntu package repository에서 bubblewrap을 설치하면 추가 AppArmor 설정 없이 작동해야 합니다. bwrap-userns-restrict profile은 apparmor package의 /etc/apparmor.d/bwrap-userns-restrict에 포함됩니다.

Ubuntu 24.04에서는 bubblewrap 설치 후에도 필요한 user namespace를 만들 수 없다는 경고가 나타날 수 있습니다. 추가 profile을 복사하고 로드합니다.

sudo apt update
sudo apt install apparmor-profiles apparmor-utils
sudo install -m 0644 \
  /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
  /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

apparmor_parser -r은 reboot 없이 profile을 kernel에 로드합니다. 모든 AppArmor profile을 다시 로드할 수도 있습니다.

sudo systemctl reload apparmor.service

해당 profile을 사용할 수 없거나 문제가 해결되지 않는다면 AppArmor unprivileged user namespace 제한을 비활성화할 수 있습니다.

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

제어 방법

대부분의 사용자는 제품의 권한 컨트롤에서 시작합니다.

Codex 앱과 IDE에서는 composer 또는 chat input 아래의 권한 선택기에서 모드를 고릅니다. 이 선택기는 Codex 기본 권한을 사용하거나, full access로 전환하거나, 사용자 지정 구성을 사용하게 합니다.

CLI에서는 세션 중 /permissions를 사용해 모드를 전환합니다.

기본값 구성

Codex가 매번 같은 동작으로 시작하게 하려면 사용자 지정 구성을 사용합니다. Codex는 이러한 기본값을 로컬 설정 파일인 config.toml에 저장합니다. 설정 기본은 작동 방식을 설명하고, 설정 참조는 sandbox_mode, approval_policy, approvals_reviewer, sandbox_workspace_write.writable_roots의 정확한 키를 문서화합니다. 이 설정으로 Codex의 기본 자율성 수준, 쓸 수 있는 디렉터리, 승인 요청 시점, 승인 요청 검토자를 결정합니다.

일반적인 샌드박스 모드는 다음과 같습니다.

  • read-only: Codex가 파일을 검사할 수 있지만 승인 없이는 파일을 편집하거나 명령을 실행할 수 없습니다.
  • workspace-write: Codex가 파일을 읽고, 워크스페이스 안에서 편집하고, 그 경계 안에서 일반 로컬 명령을 실행할 수 있습니다. 로컬 작업의 기본 low-friction 모드입니다.
  • danger-full-access: Codex가 샌드박스 제한 없이 실행됩니다. 파일 시스템과 네트워크 경계를 제거하므로 Codex가 full access로 동작하길 원할 때만 사용해야 합니다.

일반적인 승인 정책은 다음과 같습니다.

  • untrusted: Codex가 trusted set에 없는 명령을 실행하기 전에 묻습니다.
  • on-request: Codex가 기본적으로 샌드박스 안에서 작업하고, 경계를 넘어야 할 때 묻습니다.
  • never: Codex가 승인 프롬프트를 위해 멈추지 않습니다.

승인이 대화형일 때는 approvals_reviewer로 누가 검토할지도 선택할 수 있습니다.

  • user: 승인 프롬프트가 사용자에게 표시됩니다. 기본값입니다.
  • auto_review: 승인 대상 프롬프트가 reviewer 에이전트로 전달됩니다. Auto-review를 참고하십시오.

full access는 sandbox_mode = "danger-full-access"와 approval_policy = "never"를 함께 사용하는 것을 의미합니다. 반대로 위험이 더 낮은 로컬 자동화 preset은 sandbox_mode = "workspace-write"와 approval_policy = "on-request" 조합입니다. CLI flag로는 --sandbox workspace-write --ask-for-approval on-request에 해당합니다. 수동 승인을 위해 approvals_reviewer = "user"를 유지하거나, 자동 승인 검토를 위해 approvals_reviewer = "auto_review"를 설정할 수 있습니다.

Codex가 둘 이상의 디렉터리에서 작업해야 한다면 writable root를 사용해 샌드박스를 완전히 제거하지 않고 수정 가능한 위치를 확장합니다. 더 넓거나 좁은 신뢰 경계가 필요하다면 일회성 예외에 의존하기보다 기본 샌드박스 모드와 승인 정책을 조정합니다.

재사용 가능한 권한 세트에는 default_permissions를 named profile로 설정하고 [permissions.{name}.filesystem] 또는 [permissions.{name}.network]를 정의합니다. 관리형 네트워크 profile은 domain 및 socket rule에 [permissions.{name}.network.domains]와 [permissions.{name}.network.unix_sockets] 같은 map table을 사용합니다. 파일 시스템 profile은 정확한 path 또는 glob pattern에 대해 matching entry를 "none"으로 설정해 읽기를 거부할 수도 있습니다. workspace write를 끄지 않고 local secret 같은 파일을 읽을 수 없게 할 때 사용합니다.

워크플로에 특정 예외가 필요할 때는 규칙을 사용합니다. 규칙은 샌드박스 밖에서 command prefix를 allow, prompt, forbid할 수 있게 하며, 접근 범위를 넓히는 것보다 더 잘 맞는 경우가 많습니다. 앱에서 승인과 샌드박스 동작에 대한 상위 개요는 Codex 앱 기능을, IDE별 설정 진입점은 Codex IDE 확장 설정을 참고하십시오.

사용 가능한 경우 automatic review는 샌드박스 경계를 바꾸지 않습니다. 이는 샌드박스 escalation, 차단된 네트워크 접근, 여전히 승인이 필요한 side-effecting tool call처럼 경계에서 발생하는 승인 요청을 검토하는 approvals_reviewer 중 하나입니다. 샌드박스 안에서 이미 허용된 action은 추가 검토 없이 실행됩니다. reviewer lifecycle, trigger 유형, denial 의미, 구성 세부 사항은 Auto-review를 참고하십시오.

플랫폼 세부 사항은 플랫폼별 문서에 있습니다. native Windows 설정, 동작, 문제 해결은 Windows를 참고하십시오. sandboxing과 approvals에 대한 admin requirements 및 조직 수준 제약은 에이전트 승인과 보안을 참고하십시오.

Previous
프롬프팅
Next
자동 리뷰