vibebox

초고속 오픈소스 샌드박스로 코딩 에이전트를 안전하게 실행합니다.

영어 | 중국어 (간체)

VibeBox는 macOS(Apple Virtualization Framework)에서 코딩 에이전트를 실행하기 위한 프로젝트별 마이크로 VM 샌드박스입니다. 일상적인 드라이버 워크플로에 최적화되어 있습니다: 빠른 재진입, 명시적 마운트, 재사용 가능한 세션.

대상: 실제 격리를 원하면서 빠른 일상 워크플로를 포기하지 않으려는 macOS 사용자의 코딩 에이전트.

간단 요약: 제 M3에서는 재진입이 일반적으로 5초 미만 (기기/캐시에 따라 다름); 첫 실행은 Debian 기본 이미지를 다운로드하고 프로비저닝합니다 (네트워크 속도에 따라 다름).

보안 모델: vibebox.toml에서 명시적 마운트 허용 목록을 사용하는 Linux 게스트 VM (저장소 우선, 나머지는 옵트인).

• 몇 초 안에 진입/연결: vibebox 명령으로 현재 저장소에 재사용 가능한 샌드박스로 들어갑니다.
• 기본적으로 프로젝트 범위: 명시적 마운트 + 저장소 내 변경 (저장소 우선, 다른 모든 것은 허용 목록)
• 세션 기반: 다중 인스턴스 + 세션 관리 (재사용, 여러 터미널, 정리)

빠른 데모

# 아무 저장소에서
cd my-project
vibebox

다음과 같이 표시될 것입니다 (대략):

vibebox: starting (session: my-project)
vibebox: attaching...
vibecoder@vibebox:~/my-project$

VibeBox를 만든 이유

저는 매일 코딩 에이전트를 사용하며, 호스트 머신을 완전히 넘기지 않고 실제 셸을 제공하고 싶었습니다. 보안을 강화하면 지속적인 확인이 발생하고, 느슨하게 하면 파일 삭제, 비밀 노출, 저장소 이탈이 걱정됩니다.

VibeBox는 그 중간 지점입니다: 하드 VM 경계, 빠른 재진입, 명시적 마운트를 갖춘 저장소별 샌드박스입니다. 에이전트 작업을 위해 "항상 켜져" 있으면서도 안전을 부담스럽지 않게 만드는 것이 목표입니다.

왜 마이크로 VM인가? (컨테이너 대비)

컨테이너는 훌륭합니다. VibeBox는 서비스 구축을 위한 Docker/devcontainers를 대체하려는 것이 아닙니다.

저는 macOS에서 에이전트 워크플로를 위해 VM 형태의 기본값을 원했습니다:

• 기본적으로 게스트 커널 격리 경계: 에이전트가 임의 명령을 실행하도록 할 때 "안전 모드"는 호스트가 아닌 Linux 게스트여야 합니다.
• 세션을 일급 워크플로로: 저장소별로 연결/재사용, 동일한 샌드박스에 여러 터미널, 신뢰할 수 있는 정리로 유령 환경 방지.
• 기본 UX로 명시적 마운트 허용 목록: 기본적으로 저장소 범위; 다른 것은 명시적 결정.
• 저장소별 최소 설정: compose/devcontainers로 일부를 재현할 수 있지만, 기본적인 "안전 셸" 워크플로를 위해 각 저장소에서 컨테이너 설정을 유지하지 않고 단일 명령으로 작동하기를 원했습니다.

비교

기존 옵션을 사용하지 않은 이유:

• vibe: 매우 편리하고 "제로 설정, 바로 시작"을 완벽히 구현합니다. VibeBox는 의도적으로 다른 축에 있습니다: 저장소별 설정 + 세션 + 다중 인스턴스 생명주기.
• QEMU: 강력하지만, 구성 영역이 방대합니다. 일상적인 샌드박싱에는 "저장소 열고 바로 사용"이 아닙니다. 자체적인 프로젝트입니다.
• Docker / devcontainers / devpods: 훌륭한 생태계. 제 불편함은 원시 시작 시간이 아니라, 기본 워크플로를 위해 각 저장소별 에이전트 샌드박스를 기본적으로 안전하게 유지하는 일상적인 오버헤드였습니다 (마운트 허용 목록, 비밀 노출, 연결/재사용, 정리).

이것이 VibeBox를 만든 이유입니다: 빠르게 진입 가능 (그냥 vibebox), 실제 구성 + 세션 지원, 단단한 격리 경계를 유지하는 프로젝트별 샌드박스를 원했습니다.

설치

# 설치 스크립트
curl -fsSL https://raw.githubusercontent.com/robcholz/vibebox/main/install | bash

# 패키지 관리자
cargo install vibebox

# 수동 설치
curl -LO https://github.com/robcholz/vibebox/releases/download/latest/vibebox-macos-arm64.zip
unzip vibebox-macos-arm64.zip
mkdir -p ~/.local/bin
mv vibebox ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

요구 사항

• Apple Silicon이 탑재된 macOS (VibeBox는 Apple의 가상화 API 사용)

첫 실행

첫 번째 vibebox 실행은 Debian 기본 이미지를 다운로드하고 프로비저닝합니다. 이후 프로젝트별 인스턴스는 캐시된 기본 이미지를 재사용하여 훨씬 빠르게 시작됩니다.

문서

빠른 시작

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 = 5
mounts = [
    "~/.codex:~/.codex:read-write",
    "~/.claude:~/.claude:read-write",
]

[supervisor]
auto_shutdown_ms = 20000

disk_gb는 인스턴스 디스크가 처음 생성될 때만 적용됩니다. 이후 변경하려면 vibebox reset을 실행하여 디스크를 다시 생성하세요.

마운트

• 프로젝트는 읽기-쓰기로 ~/<project-name>에 마운트되며, 셸은 그 위치에서 시작됩니다.
• .git 디렉토리가 있으면 VM 내부에서 tmpfs 마운트로 가려져 게스트에서의 우발적인 편집을 방지합니다.
• 추가 마운트는 box.mounts에서 제공하며 형식은 host:guest[:read-only|read-write]입니다.
• 호스트 경로는 ~ 확장을 지원합니다. 상대 게스트 경로는 /root/<path>로 처리됩니다.
• ~를 사용하는 게스트 경로는 편의를 위해 /home/<ssh-user>에 링크됩니다. vibebox explain을 실행하여 해석된 호스트/게스트 매핑을 확인하세요.

CLI 명령

vibebox             # 현재 프로젝트 VM 시작 또는 연결
vibebox list        # 알려진 프로젝트 세션 나열
vibebox reset       # 이 프로젝트의 .vibebox 삭제 후 다음 실행 시 재생성
vibebox purge-cache # 전역 캐시 (~/.cache/vibebox) 삭제
vibebox explain     # 마운트 및 네트워크 정보 표시

VM 내부

• 기본 SSH 사용자: vibecoder
• 호스트명: vibebox
• 기본 이미지 프로비저닝 설치: 빌드 도구, git, curl, ripgrep, openssh-server, sudo
• 첫 로그인 시, VibeBox는 mise를 설치하고 uv, node, @openai/codex, @anthropic-ai/claude-code 등의 도구를 구성합니다 (최선의 노력).
• 셸 별칭: :help 및 :exit

상태 및 캐시

• 프로젝트 상태는 .vibebox/ (인스턴스 디스크, SSH 키, 로그, 관리자 소켓/pid)에 저장됩니다. vibebox reset으로 제거됩니다.
• 전역 캐시는 ~/.cache/vibebox (기본 이미지 + 공유 게스트 캐시)에 저장됩니다. vibebox purge-cache로 정리합니다.
• 세션 인덱스는 ~/.vibebox/sessions에 있으며 vibebox list로 표시됩니다.

기여

VibeBox에 기여하고 싶으시다면, 풀 리퀘스트를 제출하기 전에 기여 문서를 읽어주세요.

FAQ

다른 샌드박스와 어떻게 다른가요?

VibeBox는 최소한의 절차로 빠르고 반복 가능한 로컬 샌드박스를 위해 만들어졌습니다. 여기서 다른 점은:

• 제 M3에서는 재진입이 일반적으로 5초 미만 (기기/캐시에 따라 다름)이므로 빠르게 다시 들어갈 수 있습니다.
• 간단한 명령 vibebox 하나로 프로젝트에서 샌드박스로 들어갑니다.
• 설정은 vibebox.toml에 있으며 CPU, RAM, 디스크 크기 및 마운트를 설정할 수 있습니다.
• 세션은 일급 시민입니다: 재사용, 여러 터미널, 정리.

특별 감사

vibe by lynaghk.

그리고 놀라운 Rust 커뮤니티 — crates.io와 같은 생태계와 툴체인이 없었다면 이것은 불가능했을 것입니다!

X에서 팔로우하기 x.com/robcholz