CoCo CLI sandbox

CoCo CLI sandbox (샌드박스)

CoCo CLI는 셸 명령을 샌드박스 안에서 실행해 파일 시스템 접근, 네트워크 접근, 프로세스 기능을 제한할 수 있어요. 샌드박싱은 에이전트가 내 프로젝트 밖의 파일을 실수로 수정하거나 리소스에 접근하지 못하게 하는 격리 계층을 추가해요.

출처: CoCo CLI sandbox

본문

중요

이 기능에 대한 지원은 실험적이며 변경될 수 있어요.

참고

이 페이지는 명령을 격리하지만 여전히 내 머신에서 실행하는 로컬 샌드박스를 다뤄요. 에이전트의 도구를 Snowflake 관리 컨테이너에서 실행하려면 CoCo CLI cloud sandbox를 참고해요.

플랫폼 지원

샌드박스는 운영체제의 내장 격리 기능으로 명령을 제한해요.

플랫폼	구현	의존성
macOS	sandbox-exec(내장)	ripgrep
Linux	bubblewrap	bubblewrap, socat, ripgrep
Windows	네이티브 제한 토큰	없음

의존성 설치

macOS:

brew install ripgrep

Debian / Ubuntu:

sudo apt-get install bubblewrap socat ripgrep

Fedora / RHEL:

sudo dnf install bubblewrap socat ripgrep

샌드박스 켜기

CoCo CLI에서 /sandbox 슬래시 명령을 사용해요.

/sandbox                          # Interactive selector
/sandbox runtime on               # Enable sandbox
/sandbox runtime off              # Disable sandbox
/sandbox runtime status           # Show sandbox status
/sandbox status                   # Show current sandbox status

설정 파일에서도 샌드박스를 켤 수 있어요. ~/.snowflake/cortex/settings.json(사용자 수준) 또는 .snowflake/cortex/settings.json(프로젝트 수준)에 sandbox 객체를 추가해요.

{
  "sandbox": {
    "enabled": true
  }
}

기본 권한 모드는 "regular"예요. 자동 허용 모드를 사용하려면 "mode": "autoAllow"를 명시적으로 설정해요. Permission modes 참고.

권한 모드

샌드박스에는 명령이 어떻게 승인되는지 제어하는 두 가지 권한 모드가 있어요.

모드	설정 값	동작
Auto-allow	`"autoAllow"`	샌드박스 처리 가능한 명령은 프롬프트 없이 자동 실행돼요. 샌드박스 처리할 수 없는 명령(예: 허용되지 않은 도메인에 대한 네트워크 접근이 필요한 것)은 일반 권한 흐름으로 폴백해요.
Regular	`"regular"`	모든 명령이 샌드박스 안에서 실행되어도 승인을 프롬프트해요.

/sandbox 명령이나 설정으로 모드를 설정해요.

/sandbox mode auto                # Set auto-allow mode
/sandbox mode regular             # Set regular mode

파일 시스템 제한

샌드박스는 명령이 읽고 쓸 수 있는 경로를 제어해요.

기본 동작

작업 디렉터리: 읽기·쓰기 항상 허용.
스킬 디렉터리(~/.snowflake/cortex/skills): 허용.
컨텍스트 디렉터리(~/.snowflake/cortex/.ctx): ctxAvailable이 켜져 있을 때 허용.

보호 경로(쓰기에 항상 거부)

다음 경로는 구성과 무관하게 항상 보호돼요.

셸 구성 파일: ~/.bashrc, ~/.bash_profile, ~/.zshrc, ~/.zprofile, ~/.profile, ~/.bash_login, ~/.bash_logout
Git 훅: ~/.git/hooks, .git/hooks
SSH 구성: ~/.ssh/authorized_keys, ~/.ssh/config
관리 설정 디렉터리·파일: /Library/Application Support/Cortex/(macOS), /etc/cortex/(Linux), %ProgramData%\Cortex\(Windows)

사용자 지정 파일 시스템 규칙

설정에서 파일 시스템 접근을 구성해요.

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowRead": [],
      "denyRead": ["/private/secrets"],
      "allowWrite": ["/tmp", "~/projects"],
      "denyWrite": ["/etc", "/var"]
    }
  }
}

설정	기본값	설명
`allowRead`	`[]`(모두 허용)	샌드박스가 읽을 수 있는 경로. 빈 배열은 denyRead의 경로를 제외한 모든 경로가 허용됨을 뜻해요.
`denyRead`	`[]`	샌드박스가 읽을 수 없는 경로. allowRead보다 우선해요.
`allowWrite`	`[]`(작업 디렉터리만)	샌드박스가 쓸 수 있는 경로.
`denyWrite`	`[]`	샌드박스가 쓸 수 없는 경로. allowWrite보다 우선해요.

중요

거부 규칙은 항상 허용 규칙보다 우선해요. 경로가 allowWrite와 denyWrite 둘 다에 일치하면 그 경로는 거부돼요.

네트워크 제한

샌드박스는 명령이 네트워크로 접근할 수 있는 도메인을 제한할 수 있어요.

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["*.internal.company.com"],
      "allowLocalBinding": false
    }
  }
}

설정	기본값	설명
`allowedDomains`	`[]`(모두 허용)	샌드박스가 접근할 수 있는 도메인. 빈 배열은 deniedDomains의 도메인을 제외한 모든 도메인이 허용됨을 뜻해요. 와일드카드(`*.example.com`) 지원.
`deniedDomains`	`[]`	샌드박스가 접근할 수 없는 도메인. allowedDomains보다 우선. 와일드카드 지원.
`allowLocalBinding`	`false`	샌드박스 명령이 로컬 포트에 바인딩할 수 있는지.

샌드박스 처리 안 된 명령 폴백

일부 명령은 샌드박스와 호환되지 않을 수 있어요. allowUnsandboxedCommands 설정이 명령이 샌드박스 안에서 실행될 수 없을 때 무슨 일이 일어나는지 제어해요.

설정	동작
`true`(기본값)	에이전트가 호스트에서 명령을 실행하도록 요청할 수 있어요. 승인하도록 프롬프트해요.
`false`	명령이 샌드박스 안에서 실행되거나 `excludedCommands`에 나열되어야 해요. 둘 다 아니면 명령이 실패해요.

제외 명령

항상 호스트에서 샌드박스 밖에서 실행해야 하는 명령을 지정할 수 있어요.

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": true,
    "excludedCommands": ["docker", "kubectl"]
  }
}

제외 명령은 샌드박스를 우회하고 일반 권한 흐름을 따릅니다.

설정 참조

완전한 샌드박스 설정 객체:

{
  "sandbox": {
    "enabled": false,
    "mode": "regular",
    "allowUnsandboxedCommands": true,
    "excludedCommands": [],
    "permissions": {
      "allow": [],
      "deny": []
    },
    "network": {
      "allowedDomains": [],
      "deniedDomains": [],
      "allowLocalBinding": false
    },
    "filesystem": {
      "allowRead": [],
      "denyRead": [],
      "allowWrite": [],
      "denyWrite": []
    },
    "ctxAvailable": true
  }
}

설정	기본값	설명
`enabled`	`false`	샌드박스 켜기·끄기.
`mode`	`"regular"`	권한 모드: `"regular"` 또는 `"autoAllow"`.
`allowUnsandboxedCommands`	`true`	명령을 샌드박스 처리할 수 없을 때 호스트 실행으로 폴백 허용.
`excludedCommands`	`[]`	항상 호스트에서 샌드박스 밖에서 실행되는 명령.
`permissions.allow`	`[]`	높은 수준 권한 허용 규칙. `WebFetch(domain:example.com)`, `Edit(path)`, `Read(path)`, `Bash(command)` 같은 패턴 지원.
`permissions.deny`	`[]`	높은 수준 권한 거부 규칙. allow 규칙과 같은 패턴 구문. 허용 규칙보다 우선.
`network.allowedDomains`	`[]`	네트워크 도메인 허용 목록(빈 값 = 모두 허용). 와일드카드 지원.
`network.deniedDomains`	`[]`	네트워크 도메인 차단 목록. 허용 목록보다 우선.
`network.allowLocalBinding`	`false`	샌드박스 명령이 로컬 포트에 바인딩 허용.
`filesystem.allowRead`	`[]`	읽기 허용 목록(빈 값 = deny 제외 모두 허용).
`filesystem.denyRead`	`[]`	읽기 차단 목록. 우선.
`filesystem.allowWrite`	`[]`	쓰기 허용 목록.
`filesystem.denyWrite`	`[]`	쓰기 차단 목록. 우선.
`ctxAvailable`	`true`	컨텍스트 디렉터리(`~/.snowflake/cortex/.ctx`)에 대한 샌드박스 접근 허용. 대화 컨텍스트와 세션 데이터 저장에 사용됨.

구성 범위

샌드박스 설정은 다른 CoCo 설정과 같은 우선순위를 따라요.

프로젝트 수준(최고 우선): .snowflake/cortex/settings.json
사용자 수준: ~/.snowflake/cortex/settings.json
관리/강제: 관리자가 관리 설정 파일로 샌드박스 정책을 강제할 수 있어요. Managed settings (organization policy) 참고.

더 알아보기

CoCo CLI cloud sandbox — 클라우드 샌드박스
Permission modes — 권한 모드