SandVault - 샌드박스화된 (sandboxed) macOS 사용자 계정에서 AI 에이전트 및 셸 명령을 실행합니다. Chrome 및 iOS Simulator를 활용한 샌드박스화된 웹 및 앱 테스트를 지원합니다.

AI 준비 완료

• Claude Code, OpenAI Codex, OpenCode, Google Gemini 포함

웹 및 iOS 자동화

• Chrome / Lightpanda 및 iOS Simulator에 대한 샌드박스 접근 권한 제공

빠른 컨텍스트 전환 (Context switching)

• VM 오버헤드 없음; 즉각적인 사용자 전환 가능

비밀번호 미사용 (Passwordless)

• (설정 후) 프롬프트 없이 계정 전환 가능

공유 워크스페이스 (Shared workspace)

• /Users/Shared/sv-$USER에 대한 공동 접근 가능

심층 방어 (Defense in depth)

• 제한된 사용자 계정 + sandbox-exec 사용

깔끔한 삭제 (Clean uninstall)

• sv uninstall로 완전 제거 가능

• 웹 상호작용 테스트에 사용할 수 있도록 샌드박스 내부에서 브라우저 자동화 (Browser Automation)를 실행합니다.

• iOS 앱 테스트에 사용할 수 있도록 샌드박스 내부에서 iOS Simulator 자동화를 실행합니다.

• xcodebuild 또는 swift를 실행하려면 Sandboxing xcodebuild and swift를 참조하여 자세한 내용을 확인하세요. - sandvault 내부에서 다른 샌드박스화된 애플리케이션을 실행하려면 -x 옵션을 사용하세요. 자세한 내용은 Sandboxing other apps를 참조하세요. - 샌드박스 내부에서 GUI 애플리케이션을 실행하는 것은 불가능합니다. 자세한 내용은 Running GUI Applications를 참조하세요.

SandVault는 컴퓨터에 대해 다음과 같이 제한된 접근 권한을 가집니다:

• 홈 디렉토리(home directory)에 접근할 수 없음
• 표준 사용자 권한으로 실행됨
• 시스템 파일을 수정할 수 없음
• 마운트된 드라이브에 접근할 수 없음

- 쓰기 가능 (writable): /Users/Shared/sv-$USER -- 사용자 및 sandvault-$USER만 접근 가능
- 쓰기 가능 (writable): /Users/sandvault-$USER -- sandvault의 홈 디렉토리
- 읽기 가능 (readable): /usr, /bin, /etc, /opt -- 시스템 디렉토리
...

Homebrew를 통해 설치:

brew install sandvault

git을 통해 설치:

# 저장소 복제 (Clone)
git clone https://github.com/webcoyote/sandvault
# 옵션 1: sandvault 디렉토리를 path에 추가
...

# 샌드박스에서 Claude Code 실행
# 단축키: sv cl
sv claude
...

sandvault의 기본 모드는 명령어를 제한된 사용자 권한으로 실행합니다 (기본적으로 sudo -u sandbox-$USER COMMAND 방식입니다).

)). SandVault는 또한 제한된 sandvault 계정을 구성하여 SSH를 통해 명령어를 실행할 수 있도록 합니다 (기본적으로 ssh sandbox-$USER@$HOSTNAME 방식입니다). 이 경우 모든 기능은 동일하게 작동합니다. sv에서 SSH 모드를 사용하려면 -s 또는 --ssh 옵션을 사용하거나, 선호하는 사용자는 tmux 또는 screen을 사용할 수 있습니다.

# 사칭(impersonation)을 사용하여 실행
# sv COMMAND
sv gemini
...

# 선택적 인자를 사용하여 AI 에이전트 실행
# 사용법:
# sv <agent> [PATH] [-- AGENT_ARGUMENTS]
...

기본적으로 SandVault는 호스트 측에서 Homebrew를 통해 AI 도구들을 설치합니다. --native-install (-N) 옵션을 사용하면, 도구들이 각자의 설치 프로그램을 사용하여 샌드박스(sandbox) 내부에 설치됩니다.

Claude Code— curl -fsSL https://claude.ai/install.sh | bash를 통해 설치됩니다.

Codex— npm install -g @openai/codex를 통해 설치됩니다.

OpenCode— curl -fsSL https://opencode.ai/install | bash를 통해 설치됩니다.

Gemini— npm install -g @google/gemini-cli를 통해 설치됩니다.

도구들은 첫 실행 시 설치되며, 이후 실행 시에는 재사용됩니다.

# Claude Code를 네이티브로 설치 및 실행
sv --native-install claude
sv -N claude
...

네이티브 설치를 기본값으로 설정하려면 SANDVAULT_ARGS를 설정하세요:

# 셸 프로필(~/.zshrc, ~/.bashrc 등)에 추가
export SANDVAULT_ARGS="--native-install"
# 이제 'sv claude'는 자동으로 네이티브 설치를 사용합니다
...

명령줄 앞에 추가될 기본 인자를 제공하려면 SANDVAULT_ARGS를 설정하세요:

# 셸 프로필(~/.zshrc, ~/.bashrc 등)에 추가
export SANDVAULT_ARGS="--verbose --ssh"
# 이제 다음은 동일합니다:
...

셸 인용(Shell quoting)이 지원되므로 공백이 포함된 인자도 작동합니다:

export SANDVAULT_ARGS='--clone "my project"'

명시적인 명령줄 인자는 SANDVAULT_ARGS 뒤에 추가되므로, 나중에 처리됩니다.

# sandvault를 빌드하지만 명령어를 실행하지는 않음
sv build
sv b
...

agentsview

agentsview는 AI 코딩 에이전트(Claude Code, Codex, OpenCode, Gemini) 전반의 세션 기록, 검색 및 비용 추적을 통합하는 대시보드입니다. 호스트에 agentsview가 설치되어 있다면, sv-agentsview-setup을 통해 샌드박스 세션 데이터를 미러링하여 호스트 측 세션과 함께 표시할 수 있습니다.

# agentsview를 감지하고, 참여 여부를 묻고, 구성합니다
sv-agentsview-setup

그 다음 agentsview serve를 실행하면, agentsview 대시보드에 sandvault AI 세션이 포함된 것을 확인할 수 있습니다.

sandvault는 별도의 macOS 사용자 계정에서 실행될 뿐만 아니라, macOS의 sandbox-exec를 사용하여 애플리케이션을 실행함으로써 접근 가능한 리소스를 더욱 제한합니다.

swift와 같은 일부 애플리케이션은 이미 샌드박스(sandbox) 내부에서 실행됩니다. macOS는 중첩된(즉, 재귀적인) 샌드박스를 지원하지 않기 때문에, 이러한 애플리케이션은 실행에 실패합니다.

해결 방법은 아래 내용을 참조하세요.

swift(및 swift를 실행하는 xcodebuild)의 경우, sandvault 내부에서 실행하려면 빌드 스크립트에 다음과 같은 변수를 설정할 수 있습니다.

swift의 경우:

ARGS=()
# 중첩된 sandbox-exec를 피하기 위해 sandvault 내부에서 실행될 때 샌드박싱을 비활성화합니다
if [[ -n "${SV_SESSION_ID:-}" ]]; then
...

xcodebuild의 경우:

ARGS=()
# 중첩된 sandbox-exec를 피하기 위해 sandvault 내부에서 실행될 때 샌드박싱을 비활성화합니다
if [[ -n "${SV_SESSION_ID:-}" ]]; then
...

실행하려는 앱이 xcodebuild나 swift처럼 sandbox-exec 사용 비활성화를 지원하지 않는 경우에는 sandbox-exec 없이 sandvault를 실행할 수 있습니다.

# -x / --no-sandbox를 사용하여 sandbox-exec 사용을 비활성화합니다 (앱은 여전히 sandvault 사용자로 실행됨)
sv -x claude
sv --no-sandbox codex
...

sandbox-exec를 비활성화하면 다음과 같은 보안상의 영향이 있습니다:

• 이동식 드라이브(/Volumes/...)에 대한 읽기/쓰기 보호가 없습니다.
• o+w(0002) 파일 권한을 가진 파일 쓰기에 대한 보호가 없습니다.

# 컴퓨터에서 "전체 쓰기 가능"한(권한: `o+w` / 0002) 모든 파일을 찾으려면
# 다음 명령어를 (sandvault가 아닌) 본인의 계정에서 실행하세요:
find / \
...

샌드박스 (sandbox)가 제대로 작동하지 않는 경우, 재빌드 (rebuild)하거나 삭제 후 재설치 (uninstall/reinstall)하여 수정할 수 있습니다. 두 방법 모두 안전하며, 공유 샌드박스 (shared sandbox) 폴더의 파일은 삭제되지 않습니다.

# 강제 재빌드 (Force rebuild)
sv --rebuild build
# 삭제 후 재설치
...

위와 같은 보안 팝업이 나타난다면, 이는 공유 sandvault 디렉토리 내의 파일에 올바른 ACL (Access Control Lists)이 설정되어 있지 않기 때문일 수 있습니다. 이는 다른 사용자의 파일을 sandvault 공유 디렉토리 (/Users/Shared/sv-$USER)로 복사했을 때 발생합니다. 이 문제는 재빌드 명령어인 sv --rebuild build를 실행하거나, 모든 명령어에 재빌드 플래그를 추가함으로써 (예: sv -r shell) 수정할 수 있습니다. 이 작업은 한 번만 수행하면 됩니다.

sv를 실행할 때 "Permission denied" (권한 거부) 오류가 발생한다면, 사용 중인 셸 (shell)의 umask 설정이 제한적일 수 있습니다 (예: 기본값인 022 대신 077 사용). 다음 명령어로 확인하세요:

umask

SandVault는 이를 감지하고 경고를 보냅니다. 현재 세션에 대해 이를 수정하려면 --fix-permissions 플래그를 추가하세요:

# 권한 수정 (단독 실행 또는 빌드와 함께 실행)
sv --fix-permissions
sv --fix-permissions build

만약 이전에 제한적인 umask 환경에서 Homebrew를 설치했다면, Homebrew의 디렉토리 권한도 수정해야 할 수 있습니다:

sudo chmod -R o+rX /opt/homebrew

sandvault를 사용하고 있다면, 아마도 사용자 정의 셸 설정 파일 (custom shell configuration files)을 사용하는 분일 것이며, sv shell을 실행하는 동안 기본 zsh를 사용해야 한다면 실망할 것입니다. SandVault에 사용자 정의 설정을 적용하는 방법은 다음과 같습니다:

• sandvault build, sandvault shell, sandvault claude 등의 명령어를 실행하여 sandvault가 설치되었는지 확인합니다.
• 원하는 설정 파일 (예: .zshrc, .zprofile 등)을 /Users/Shared/sv-${USER}/user/로 복사합니다.

다음번에 sandvault를 실행하면, 파일들이 sandvault 사용자 홈 디렉토리로 복사되고 zsh 설정 파일들이 소싱 (sourced)됩니다:

.zshenv → .zprofile → .zshrc
참고: .zlogin 및 .zlogout는 지원되지 않음

참고: 이전 버전의 sandvault는 guest/home/user/에 있는 설정 파일을 지원했습니다.

, 이는 Homebrew 설치의 경우 작동하지 않았습니다. 결과적으로 이 방식은 더 이상 지원되지 않으며, guest/home/user를 /Users/Shared/sv-${USER}/user/로 이동하라는 오류 메시지를 받게 됩니다.

SandVault는 샌드박스 내부에서의 자동화를 위해 헤드리스 브라우저 (headless browser)를 지원합니다. 브라우저는 호스트 (host) 측에서 실행되며, 샌드박스는 localhost를 통해 Chrome DevTools Protocol (CDP)로 브라우저에 연결됩니다. 두 가지 백엔드가 지원됩니다: Chrome (기본값) 및 Lightpanda.

# 브라우저 지원과 함께 실행 (기본값은 Chrome)
sv --browser claude
sv --browser shell
...

샌드박스 내부에서 SV_BROWSER_ENDPOINT 환경 변수는 CDP 엔드포인트 URL (예: http://127.0.0.1:52858)을 포함합니다.

// Playwright
const browser = await chromium.connectOverCDP(process.env.SV_BROWSER_ENDPOINT);
// Puppeteer
...

호스트에서 엔드포인트 URL을 조회할 수 있습니다:

# CDP 엔드포인트 URL을 출력합니다 (브라우저를 사용할 수 없는 경우 오류 발생)
sv --endpoint

Playwright 및 Puppeteer 사용 예시는 ./tests/browser/*.js를 참조하세요. 프롬프트에 대해서는 guest/home/bin/prompts/browser.md를 참조하세요.

• 브라우저는 호스트 측에서 헤드리스 (headless)로 실행되며 (SandVault 세션당 하나), 샌드박스는 localhost를 통해 연결됩니다.

SandVault는 iOS 앱 테스트를 위해 샌드박스화된 AI 에이전트에게 iOS 시뮬레이터 (iOS Simulator)를 노출할 수 있습니다. 시뮬레이터는 호스트에서 실행됩니다 (GUI 앱이므로 샌드박스 내부에서 실행될 수 없습니다). localhost의 HTTP 브릿지 (bridge)가 샌드박스 측의 요청을 xcrun simctl 및 iosef 호출로 변환합니다.

# iOS 시뮬레이터 지원과 함께 실행
sv --ios claude
sv --ios shell

대화형으로 디버깅하거나 에이전트의 동작을 관찰할 때 유용한 --ios-gui를 추가하면 Simulator.app 창도 함께 표시됩니다:

sv --ios-gui shell

다른 시뮬레이터(사용자의 것이나 다른 도구의 것)가 방해받지 않도록 세션 종료 시에도 Simulator.app은 실행 상태로 유지됩니다.

샌드박스 내부에서 SV_IOS_SIMULATOR_ENDPOINT 환경 변수는 HTTP 브릿지를 가리킵니다 (예: http://127.0.0.1:52861).

# 시뮬레이터 준비 상태 확인
curl $SV_IOS_SIMULATOR_ENDPOINT/ready
# 접근성 트리 (accessibility tree) 읽기
...

전체 엔드포인트(endpoints) 목록은 guest/home/bin/prompts/ios-simulator.md를 참조하세요. 이 파일은 --ios 또는 --ios-gui를 사용할 때 AI 에이전트 프롬프트(prompt)에 자동으로 포함됩니다. 실행 가능한 예제는 tests/ios-simulator/scripts/tests를 참조하세요.

• 각 --ios 세션마다 호스트에서 새로운 스크래치 시뮬레이터(이름: sandvault-<session-id>)가 생성 및 부팅되며, 종료 시 삭제됩니다.

• Python HTTP 브릿지(helpers/sv-ios-bridge)가 동적 localhost 포트에서 대기하며, 화이트리스트(whitelisted)에 등록된 iosef 및 xcrun simctl 서브커맨드(subcommands)를 전면(front)에서 처리합니다.

• /install로 전달되는 .app 번들은 반드시 /Users/Shared/ 하위에 있어야 합니다 (샌드박스 사용자가 이미 접근할 수 있도록 하기 위함). 브릿지는 해당 트리 외부의 경로는 거부합니다.

• 모든 서브프로세스(subprocess) 호출은 셸(shell)이 아닌 명시적인 argv 리스트를 사용합니다.

• 최소 하나 이상의 iOS 런타임(runtime)이 설치된 Xcode (Xcode → Settings → Platforms).

• Homebrew (iosef를 설치하는 uv를 설치하는 데 사용됨). sandvault는 첫 사용 시 두 가지 모두를 자동으로 설치합니다.

요약(TL;DR): 죄송합니다, macOS의 보안 제한으로 인해 이 기능은 작동하지 않습니다.

메인 계정의 리소스에 대한 접근을 제한하기 위해 샌드박스 계정에서 GUI 애플리케이션(예: 브라우저, Claude Desktop)을 실행할 수 있다면 매우 좋을 것입니다.

문제는 애플리케이션이 다른 사용자가 소유한 WindowServer에 보고할 수 없다는 점인 것으로 보입니다.

인터넷 게시글들에 따르면 sudo su, sudo launchctl asuser, 그리고 sudo launchctl bsexec를 사용하여 가능하다고 제안하지만, 해당 답변들은 오래된 것이며 Apple의 macOS 보안 개선으로 인해 이러한 통로들이 차단되었을 가능성이 높습니다.

혹시 해결 방법을 찾으신다면, 부디 PR(Pull Request)을 보내주세요 :)

Docker 컨테이너, Podman, sandbox-exec, 그리고 가상화(virtualization)를 탐색한 끝에, 저는 다음과 같은 기능이 필요했습니다:

• 가상화 오버헤드(overhead) 없이 macOS에서 네이티브로 작동할 것

• 너무 복잡하지 않으면서도 의미 있는 격리(isolation)를 제공할 것

• Claude Code를 --dangerously-skip-permissions 옵션과 함께 실행할 수 있을 것

• --dangerously-bypass-approvals-and-sandbox 옵션과 함께 OpenAI Codex 실행

• OPENCODE_PERMISSION='{"*":"allow"}'와 함께 OpenCode 실행

• --yolo 옵션과 함께 Google Gemini 실행

• 웹 테스트를 위한 Chrome 자동화 (Chrome DevTools Protocol 경유)

• 앱 테스트를 위한 iOS Simulator 자동화 (xcrun simctl 및 iosef 경유)

• 신뢰할 수 있는 코드와 신뢰할 수 없는 코드 사이의 깨끗한 분리 유지

SandVault는 macOS의 Unix 유산과 사용자 계정 시스템을 사용하여 단순하지만 효과적인 샌드박스 (Sandbox)를 생성합니다.

• ClodPod는 macOS 가상 머신 (Virtual Machine) 내부에서 Claude Code를 실행합니다.
• Chamber는 macOS 가상 머신 내부에서 Claude Code를 실행하기 위한 개념 증명 (Proof-of-concept) 앱입니다.
• Claude Code Sandbox는 Docker 컨테이너 (Linux)에서 Claude Code를 실행합니다.

Apache License, Version 2.0

SandVault Copyright © 2026 Patrick Wyatt

자세한 내용은 LICENSE.md를 참조하십시오.

기여와 버그 보고를 환영합니다.