FRELY / BLOG
AI가 컴퓨터에서 명령을 실행할 때 샌드박스 런타임이 하는 일
AI가 컴퓨터에서 셸 명령을 실행하도록 허용하면 유용합니다. 의존성을 설치하고, 테스트를 실행하고, 로그를 읽고, 빌드를 고칠 수 있습니다. 동시에 이는 사용자가 직접 작성하지 않은 프로그램이, 검토하지 않은 텍스트에 의해 움직이며, 사용자 계정 권한으로 실행된다는 뜻이기도 합니다.
기본적으로 이 계정은 SSH 키, 클라우드 자격 증명, 패키지 레지스트리 토큰, 브라우저 프로필을 읽을 수 있습니다. 명령이 악의적이지 않아도 피해를 일으킬 수 있습니다. 웹 페이지나 이슈 댓글에 숨어 있는 프롬프트 인젝션 하나면, 아주 평범해 보이는 명령이 비밀 값을 읽어 어딘가로 보내게 만들 수 있습니다.
모든 명령마다 “괜찮으시겠습니까?”라고 묻는 것으로는 이 문제가 해결되지 않습니다. 사람은 온전히 읽을 수 없는 것을 그래도 승인합니다. 더 나은 답은 위험한 일을 기본적으로 불가능하게 만들고, 정말 필요할 때에만 사람이 좁은 문을 열도록 허용하는 것입니다. 샌드박스가 바로 그런 목적으로 쓰입니다.
srt란 무엇인가
srt는 Anthropic의 오픈소스 샌드박스 런타임(@anthropic-ai/sandbox-runtime)입니다. Claude Code를 위해 만들어졌으며, 명령줄 도구로도 라이브러리로도 사용할 수 있습니다. 임의의 프로세스와 그 프로세스가 시작하는 모든 것을, 운영체제가 강제하는 파일 및 네트워크 제한으로 감쌉니다. 컨테이너 이미지도 가상 머신도 없습니다.
프로젝트 자체 README는 이것을 베타 리서치 프리뷰라고 부릅니다. 따라서 완성된 보장이라기보다는 강력한 구성 요소로 취급하는 것이 좋습니다.
파일을 제한하는 방법
파일 규칙은 단순하게 요약할 수 있습니다:
- 읽기는 기본적으로 모든 곳에서 허용됩니다.
denyRead로 숨길 위치를 나열합니다. 예를 들어 자격 증명 폴더 같은 곳입니다. - 쓰기는 기본적으로 모든 곳에서 거부됩니다.
allowWrite로 명령이 쓸 수 있는 위치를 나열하며, 보통 프로젝트 폴더와 임시 디렉터리입니다.denyWrite가allowWrite보다 우선하므로, 허용된 폴더 안에서 특정 파일만 보호 대상으로 빼낼 수 있습니다.
읽기 쪽은 허용 목록이 아니라 거부 목록 방식입니다. 도구들이 많은 시스템 파일을 읽어야 하므로 실용적인 선택이지만, 그만큼 샌드박스는 누군가 나열할 생각을 한 것만 숨긴다는 뜻이기도 합니다.
네트워크를 제한하는 방법
기본적으로는 네트워크 접근이 전혀 허용되지 않습니다. 명령은 샌드박스 바깥에서 실행되는 프록시를 통해서만 네트워크에 도달할 수 있고, 어떤 도메인이 허용되는지는 그 프록시들이 결정합니다.
- macOS: 명령은 생성된 Seatbelt 프로필(
sandbox-exec) 아래에서 실행되며, 로컬 프록시 포트와의 통신만 허용됩니다. - Linux: 명령은 네트워크 네임스페이스가 제거된 bubblewrap 아래에서 실행되므로, 샌드박스 안에 마운트된 Unix 소켓을 통해 프록시에 연결하는 것이 유일한 외부 통로입니다.
HTTP와 HTTPS는 HTTP 프록시를 통해 처리됩니다. 그 외의 TCP 트래픽은 SOCKS5 프록시를 거칩니다. 두 프록시 모두 도메인 허용 및 거부 목록을 강제합니다. Unix 소켓은 기본적으로 차단됩니다.
이 접근 방식이 좋은 이유
이 제한은 운영체제 안에 자리 잡고 있습니다. AI의 선의에 의존하는 것도, 명령 이름 목록에 의존하는 것도 아닙니다. 명령은 다시 쓰이거나, 스크립트로 감싸지거나, 난독화될 수 있습니다. 그래도 샌드박스가 숨긴 폴더를 읽거나 허용된 폴더 바깥에 쓸 수는 없습니다. 같은 규칙이 모든 자식 프로세스에 적용됩니다.
srt가 하지 않는 것
샌드박스는 마법 방패가 아닙니다. 무엇을 믿고 맡길 수 있는지를 결정하는 것이 바로 이 한계들이므로, 솔직하게 짚고 넘어갈 가치가 있습니다.
- 설정만큼만 단단합니다. 네트워크 허용 목록이 열려 있으면, 명령이 읽을 수 있는 것은 무엇이든 밖으로 보낼 수 있습니다. 비밀 값이 거부 목록에 없다면 샌드박스는 그것을 숨기지 않습니다.
- 베타 소프트웨어입니다. 프로젝트 스스로 그렇게 말하며, 옵션은 바뀔 수 있습니다.
- 플랫폼별 차이. macOS와 Linux를 지원합니다. Linux에서는 bubblewrap, socat, ripgrep이 필요합니다. Windows 지원은 srt에서 알파 단계이며, Frely CLI는 Windows에서 샌드박스 명령을 실행하지 않습니다.
- 일부 옵션은 의도적으로 제한을 약화시킵니다. Unix 소켓 허용, 중첩 샌드박스, Apple Events 허용은 각각 격리를 우회하는 길을 열어 줍니다. README도 이에 대해 경고합니다.
- 하나의 명령이 만드는 프로세스 트리만 제한합니다. AI에게 비밀번호를 직접 알려 주는 사람이나, 샌드박스에서 직접 파일을 복사해 내는 행위로부터는 보호해 주지 않습니다.
Frely CLI가 srt를 사용하는 방식
Frely CLI는 AI에서 컴퓨터를 제어할 수 있게 해 줍니다. AI가 요청하고, CLI가 사용자 기기에서 명령을 실행하는 방식입니다. Frely CLI가 원격 AI 클라이언트를 위해 실행하는 모든 명령은 먼저 srt를 거칩니다. 이것이 실제로 어떻게 동작하는지, CLI 소스 코드를 기준으로 살펴보겠습니다.
기본 동작
- 쓰기: 명령은 워크스페이스 폴더와 시스템 임시 디렉터리 안에만 쓸 수 있습니다. 그 외에는 어디에도 쓸 수 없습니다.
- 자격 증명 폴더는 숨겨집니다. CLI는 SSH 키, AWS, Google Cloud, Kubernetes, GitHub CLI 설정, GnuPG 키, 저장된 git 자격 증명, 패키지 레지스트리 토큰 파일(
.npmrc,.pypirc, Cargo 자격 증명)에 대한 읽기를 거부합니다. Frely 자체의 기기 자격 증명은 어떤 승인으로도 절대 열 수 없습니다. - 민감한 위치는 쓰기 보호가 유지됩니다.
.zshrc,.bashrc같은 셸 시작 파일, macOS LaunchAgents, 자격 증명 폴더는 쓰기로부터 보호됩니다. “내 홈 폴더 아래에 쓰기” 같은 넓은 권한에는 이들이 포함되지 않습니다. 하나를 열려면 정확한 경로를 지정해야 합니다. .git/hooks는 계속 차단됩니다. 훅은 샌드박스 바깥에서 프로그램을 실행하므로, 어떤 승인으로도 열 수 없습니다.- 안전 쪽으로 실패합니다(fail closed). 기기에서 샌드박스를 시작할 수 없는 경우(지원하지 않는 플랫폼이거나 의존성이 없는 경우)에는 이유를 알려 주는 메시지와 함께 명령이 거부됩니다. 샌드박스 없이 조용히 실행되는 일은 결코 없습니다.
더 필요한 것은 좁게 요청
명령이 샌드박스가 숨긴 무언가를 필요로 할 때, AI가 그냥 가져갈 수는 없습니다. AI가 요청하면 기기 소유자가 Frely 웹사이트에서 패스키나 인증 앱 코드로 승인합니다. 채팅에서 버튼을 누르는 방식이 아닙니다. 요청에는 이유와 정확한 명령이 적혀 있습니다. 승인은 자격 증명 그룹 하나(예를 들어 SSH는 되고 AWS는 안 되는 식), 캐시 폴더 하나, 또는 특정 디렉터리 하나만큼 좁게 설정할 수 있습니다.
이렇게 좁힐 수 있는 것이 하나도 없을 때, 소유자는 샌드박스 없이 명령을 실행하도록 승인할 수 있습니다. 그것은 마지막 선택지이지 기본값이 아니며, CLI의 거부 메시지는 AI에게 가장 좁은 옵션부터 요청하도록 유도합니다.
문을 통째로 넘겨 주지 않고 Git 사용하기
srt는 저장소의 .git/config에 대한 쓰기를 차단합니다. git 설정은 나중에 git이 샌드박스 바깥에서 프로그램을 실행하도록 만들 수 있기 때문입니다. 이로 인해 git push -u, git remote add 같은 일상적인 명령도 함께 막힙니다.
Frely CLI는 일반적인 명령에는 이런 쓰기를 허용한 다음 검사합니다. 명령을 실행하기 전에 워크스페이스의 각 .git/config 사본을 만들어 두고, 명령이 끝난 뒤 비교하여, 추가된 설정 중 git이 프로그램을 실행하게 만드는 것(fsmonitor, 자격 증명 헬퍼, 사용자 지정 페이저, 셸 별칭 같은)을 제거합니다. 그 결과는 무엇이 제거되었는지 AI에게 알려 줍니다. 명령이 백그라운드에 남겨 둔 프로세스는 중지시킵니다.
샌드박스 안에서의 네트워킹
srt는 HTTP, HTTPS, SOCKS 트래픽만 처리하므로 ssh 같은 도구에는 도움이 필요합니다. CLI는 ssh, scp, sftp를 샌드박스의 프록시를 통해 라우팅합니다. 데이터베이스 클라이언트와 그 밖의 raw TCP 도구를 위해서는 내장된 frely tunnel이 샌드박스 안에 로컬 포트를 열어 줍니다. 로컬 프록시(예: Clash)를 통해 인터넷에 접속한다면 frely sandbox proxy로 샌드박스가 이를 사용하게 할 수 있습니다. Frely는 프록시 설정을 읽기만 하며, 변경하지 않습니다.
Frely CLI의 srt 활용이 다루지 않는 것
저희는 이 경계를 숨기지 않고 알려 드리는 편을 택합니다:
- 외부로 나가는 네트워크는 기본적으로 열려 있습니다. CLI는 명령이 어떤 도메인에 도달할 수 있는지 제한하지 않습니다. npm, pip, git, curl이 계속 동작하도록 하기 위함입니다. 그만큼 사용자 데이터를 지키는 것은 파일 규칙이라는 뜻입니다. 샌드박스가 읽을 수 있는 비밀 값은 밖으로 보낼 수도 있습니다. 보호는 네트워크를 막는 데서가 아니라, 자격 증명을 닿을 수 없는 곳에 두는 데서 나옵니다.
- 홈 폴더의 대부분은 읽을 수 있습니다. 거부 목록은 잘 알려진 자격 증명 위치를 다루며, 모든 개인 파일을 다루지는 않습니다. 다른 곳에 둔 파일(다른 프로젝트의
.env파일, 메모, 문서)은 샌드박스에서 실행 중인 명령이 읽을 수 있습니다. - 승인된 접근은 실제 접근입니다. SSH 키 접근을 승인하면 명령은 그 키를 읽을 수 있습니다. 이해하는 것만 승인하고, 가능한 한 가장 좁은 옵션을 고르세요.
.git/config보호는 사후 검사입니다. 명령이 끝난 뒤 위험한 설정을 되돌립니다. git의 알려진 프로그램 실행 설정을 검사 대상으로 삼으며, 스스로 한계도 밝힙니다. 명령 사이 정리 과정을 빠져나간 프로세스는 즉시가 아니라 다음 검사 때 잡힙니다.- 명령을 가두는 것이지 사람을 가두는 것이 아닙니다. 샌드박스는 명령이 만질 수 있는 것을 제한합니다. 현명하지 못한 승인을 막아 주지 않으며, 잠긴 화면이나 강력한 계정 로그인의 대체품도 아닙니다.
- srt는 베타 리서치 프리뷰이며, Frely CLI도 그 지위를 그대로 이어받습니다.
요약
명령을 실행할 수 있는 AI는 그 명령을 둘러싼 벽만큼 안전합니다. srt는 운영체제 수준에서 그 벽을 세웁니다. 프로젝트 외에는 어디에도 쓰지 못하게 하고, 자격 증명 폴더를 숨기고, 네트워크 트래픽을 관문을 통해 보내는 것입니다. Frely CLI는 이 벽을 기본적으로 유지하고, 그것을 여는 일을 신중하고 좁으며 사람이 승인한 절차로 만들고, 다루지 않는 부분은 분명하게 알려 드립니다.