<p align="center">
<a href="https://vibebox.robcholz.com">
<picture>
<img src="https://raw.githubusercontent.com/robcholz/vibebox/HEAD/docs/banner.png" alt="VibeBox 로고">
</picture>
</a>
</p>
<p align="center">코딩 에이전트를 안전하게 실행하기 위한 초고속 오픈소스 샌드박스입니다.</p>
<p align="center">
<a href="https://crates.io/crates/vibebox">
<img alt="Crates.io" src="https://img.shields.io/crates/v/vibebox.svg">
</a>
<a href="https://github.com/robcholz/vibebox/blob/main/LICENSE">
<img alt="MIT 라이선스" src="https://img.shields.io/badge/license-MIT-blue.svg">
</a>
<a href="https://github.com/robcholz/vibebox/actions?query=workflow%3ACI+branch%3Amain">
<img alt="빌드 상태" src="https://github.com/robcholz/vibebox/workflows/CI/badge.svg">
</a>
</p>
<p align="center">
<a href="README.md">English</a> |
<a href="README.zh.md">简体中文</a>
</p>
VibeBox는 macOS에서 코딩 에이전트를 실행하기 위한 프로젝트별 마이크로 VM(micro-VM) 샌드박스입니다 (Apple Virtualization Framework 사용).
이는 빠르고 따뜻한 재진입(warm re-entry), 명시적 마운트(explicit mounts), 그리고 재사용 가능한 세션을 특징으로 하는 '일상적인 사용 환경(daily-driver)' 워크플로우에 최적화되어 있습니다.
대상 사용자: 빠르고 일상적인 워크플로우를 포기하지 않으면서 실제 격리(real isolation)가 필요한 코딩 에이전트 실행 macOS 사용자.
간단한 사실: 따뜻한 재진입 시간은 일반적으로 M3에서 5초 미만입니다 (기기/캐시에 따라 다름). 첫 실행 시에는 Debian 기본 이미지를 다운로드하고 프로비저닝합니다 (네트워크 의존적).
보안 모델: vibebox.toml에서 명시적으로 지정된 마운트 허용 목록(allowlist)을 사용하는 Linux 게스트 VM입니다 (저장소 우선(repo-first), 그 외 모든 것은 선택적 참여(opt-in)).
- 몇 초 만에 진입/연결:
vibebox가 현재 저장소(repo)를 위한 재사용 가능한 샌드박스 환경으로 사용자를 안내합니다.
- 기본적으로 프로젝트 범위 한정: 명시적 마운트와 저장소 내 변경 사항(저장소 우선, 그 외 모든 것은 허용 목록에 포함됨)을 사용합니다.
- 세션 관리: 다중 인스턴스와 세션 관리 기능(재사용, 여러 터미널, 정리)을 제공합니다.
간단한 데모
보게 될 내용 (대략적으로):
vibebox: starting (session: my-project)
vibebox: attaching...
vibecoder@vibebox:~/my-project$
VibeBox Terminal UI
VibeBox를 구축한 이유
저는 코딩 에이전트를 매일 사용하며, 호스트 머신 자체를 넘겨주지 않으면서 실제 셸(shell)을 제공하고 싶었습니다.
너무 제한하면 끊임없는 확인 절차가 필요하고, 너무 느슨하게 하면 파일을 삭제하거나, 비밀 정보(secrets)를 건드리거나, 리포지토리(repo) 외부로 벗어날까 봐 걱정해야 합니다.
VibeBox는 중간 지점입니다. 이는 강력한 VM 경계(boundary)를 가진 리포지토리별 샌드박스이며, 빠른 재진입(re-entry)과 명시적 마운트(explicit mounts) 기능을 제공합니다. 안전성을 귀찮은 일이 아닌 '항상 작동하는' 에이전트 작업 환경으로 만들기 위해 설계되었습니다.
마이크로 VM을 사용한 이유 (컨테이너 대비)?
컨테이너는 훌륭합니다. VibeBox가 빌드 서비스용으로 Docker/devcontainers를 대체하려는 것은 아닙니다.
저는 macOS에서 에이전트 워크플로우에 대해 VM 형태의 기본 설정을 원했습니다:
- 기본 게스트 커널 격리 경계(guest-kernel isolation boundary): 에이전트가 임의 명령을 실행하도록 할 때, '안전 모드'가 호스트가 아닌 리눅스 게스트였으면 좋겠습니다.
- 일급 워크플로우로서의 세션(sessions): 리포지토리별로 연결/재사용 가능하며, 동일한 샌드박스에 여러 터미널을 넣고 고아 환경(orphan environments)을 방지하는 신뢰할 수 있는 정리 기능이 필요합니다.
- 주요 사용자 경험(UX)으로서의 명시적 마운트 허용 목록(explicit mount allowlists): 기본적으로 리포지토리 범위로 제한되며, 그 외의 모든 것은 명시적인 결정이 필요합니다.
- 최소한의 리포지토리별 설정(minimal per-repo setup): compose/devcontainers로 일부를 재현할 수는 있지만, 기본적인 '안전 셸' 워크플로우에 대해 컨테이너 설정을 유지하지 않고도 리포지토리 간 작동하는 단일 명령어를 원했습니다.
비교
기존 옵션을 사용하지 않은 이유입니다:
- vibe: 매우 편리하며 "설정 없음(zero-config), 바로 사용"을 구현합니다. VibeBox는 의도적으로 다른 축에 위치합니다: 리포지토리별 설정(per-repo config) + 세션 + 다중 인스턴스 수명 주기 관리입니다.
- QEMU: 강력하지만, 설정 영역(configuration surface area)이 매우 큽니다. 일상적인 샌드박싱의 경우 "리포지토리를 열고 바로 사용"하는 것이 아니라 그 자체로 하나의 프로젝트가 됩니다.
- Docker / devcontainers / devpods: 훌륭한 생태계입니다. 제가 느낀 마찰(friction)은 순수한 시작 시간이 아니라, 기본적인 워크플로우를 위해 리포지토리별 컨테이너 설정을 유지하지 않으면서도 리포지토리별 에이전트 샌드박스를 기본적으로 안전하게 (마운트 허용 목록, 비밀 노출, 연결/재사용, 정리) 유지하는 일상적인 오버헤드였습니다.
이것이 제가 VibeBox를 구축하게 된 동기였습니다: 저는 진입 속도가 빠르고(단순히 vibebox 실행), 실제 설정 및 세션을 지원하며, 강력한 격리 경계(hard isolation boundary)를 유지하는 프로젝트별 샌드박스를 원했습니다.
설치 (Installation)
curl -fsSL https://raw.githubusercontent.com/robcholz/vibebox/main/install | bash
...
요구 사항 (Requirements)
- Apple Silicon을 탑재한 macOS (VibeBox는 Apple의 가상화 API를 사용합니다).
첫 실행 (First Run)
최초의 vibebox 실행은 Debian 기본 이미지를 다운로드하고 이를 프로비저닝(provision)합니다. 그 이후에는 프로젝트별 인스턴스가 캐시된 기본 이미지를 재사용하여 훨씬 빠르게 시작됩니다.
문서화 (Documentation)
빠른 시작 (Quick Start)
cd /path/to/your/project
vibebox
첫 실행 시 VibeBox는 프로젝트 내에 vibebox.toml을 생성하고(없을 경우), 인스턴스 데이터를 위한 .vibebox/ 디렉토리를 만듭니다.
설정 파일 (vibebox.toml)
기본적으로 vibebox.toml은 프로젝트 루트에 위치합니다. 이 파일을 vibebox -c path/to/vibebox.toml 또는 VIBEBOX_CONFIG_PATH 환경 변수를 사용하여 덮어쓸 수 있지만, 경로는 반드시 프로젝트 디렉토리 내부에 있어야 합니다.
기본 설정 (누락 시 자동 생성):
[box]
cpu_count = 2
ram_mb = 2048
...
disk_gb는 인스턴스 디스크가 처음 생성될 때만 적용됩니다. 나중에 이 값을 변경하려면 vibebox reset을 실행하여 디스크를 재구성해야 합니다.
마운트 (Mounts)
- 프로젝트는
~/<project-name>에서 읽기-쓰기(read-write)로 마운트되며, 셸은 그곳에서 시작됩니다.
.git 디렉토리가 존재하는 경우, 게스트가 실수로 편집하는 것을 방지하기 위해 VM 내부의 tmpfs 마운트로 가려집니다 (masked).- 추가적인 마운트는
box.mounts에서 host:guest[:read-only|read-write] 형식으로 가져옵니다.
- 호스트 경로는
~ 확장을 지원합니다. 상대 게스트 경로는 /root/<path>로 처리됩니다.
~를 사용하는 게스트 경로는 편의를 위해 /home/<ssh-user>에 연결(linked)됩니다. 해석된 호스트/게스트 매핑을 보려면 vibebox explain을 실행하십시오.
CLI 명령어
vibebox
vibebox list
vibebox reset
...
VM 내부 환경
- 기본 SSH 사용자:
vibecoder
- 호스트 이름(Hostname):
vibebox
- 베이스 이미지 프로비저닝 설치 항목: 빌드 도구,
git, curl, ripgrep, openssh-server, 그리고 sudo가 설치됩니다.
- 첫 로그인 시 VibeBox는
mise를 설치하고 uv, node, @openai/codex, @anthropic-ai/claude-code와 같은 도구들을 구성합니다 (최선의 노력으로).
- 셸 별칭(Shell aliases):
:help 및 :exit.
상태 및 캐시(State & Cache)
- 프로젝트 상태는
.vibebox/에 저장됩니다 (인스턴스 디스크, SSH 키, 로그, 매니저 소켓/PID). vibebox reset이 이를 제거합니다.
- 전역 캐시는
~/.cache/vibebox에 저장됩니다 (베이스 이미지 + 공유 게스트 캐시). vibebox purge-cache로 지울 수 있습니다.
- 세션 인덱스는
~/.vibebox/sessions에 있으며, vibebox list로 확인할 수 있습니다.
기여(Contributing)
VibeBox에 기여하는 데 관심이 있다면, 풀 리퀘스트를 제출하기 전에 기여 가이드를 읽어주십시오.
FAQ
다른 샌드박스와 무엇이 다른가요?
VibeBox는 최소한의 절차로 빠르고 반복 가능한 로컬 샌드박스를 위해 구축되었습니다. 여기서 다른 점은 다음과 같습니다:
- 따뜻한 재진입(Warm re-entry)은 보통 제 M3 칩에서 5초 미만입니다 (장치/캐시에 따라 다름). 따라서 빠르게 다시 작업에 몰입할 수 있습니다.
- 간단한 명령어 하나인
vibebox만으로 프로젝트에서 샌드박스(sandbox) 내부로 진입할 수 있습니다.
- 설정은
vibebox.toml 파일에 존재하며, 여기서 CPU, RAM, 디스크 크기 및 마운트(mounts)를 설정할 수 있습니다.
- 세션은 최우선 순위로 다뤄집니다 (first-class): 재사용, 여러 터미널 지원, 정리(cleanup) 기능이 제공됩니다.
특별 감사
lynaghk의 vibe.
그리고 놀라운 Rust 커뮤니티 덕분입니다. crates.io와 같은 생태계(ecosystem) 및 툴체인(toolchain)이 없었다면 이것은 불가능했을 것입니다!
X에서 저를 팔로우하세요 x.com/robcholz
