
코딩 에이전트에게 노트북이 아닌 일회용 Linux VM을 제공하세요
코딩 에이전트는 실제로 작업을 하게 할 때만 유용합니다: 패키지 설치, 작성한 코드 실행, 서버 시작, 네트워크 사용. 당신의 머신에서는 두 가지 나쁜 선택지가 남습니다. 모든 명령을 승인하거나(몇 초마다 프롬프트를 지켜봐야 함), --dangerously-skip-permissions를 실행하고 중요한 것이 rm -rf 한 번이나 토큰 유출 하나로 사라지지 않기를 바라는 것입니다.
clawk는 세 번째 선택지입니다. 저장소에 cd한 뒤 clawk를 입력하면, Claude Code(또는 Codex, pi, 셸)가 임시 Linux VM 안에서 작업합니다(코드는 마운트되고, 게스트에서 root 권한, 권한 프롬프트 없음). 그동안 당신의 파일, 키체인, 그리고 나머지 머신은 손이 닿지 않는 곳에 있습니다. 에이전트는 당신의 머신 대신 자신만의 머신을 얻습니다.
작동하는 에이전트까지 한 번의 명령; 알 수 없는 서버로 데이터를 보내려는 시도가 네트워크 허용 목록에 의해 차단됨; clawk attach가 나중에 세션을 재개.
경계는 에이전트가 설득당할 수 있는 프롬프트의 규칙이 아닙니다. 그것은 별도의 머신이며, 유일한 통로는 당신이 마운트한 것들뿐입니다. 샌드박스 안의 셸에서:```console $ curl https://tracker.evil.example # not on the allow-list: blocked curl: (7) Failed to connect to tracker.evil.example port 443 after 2 ms: Connection refused
$ cat ~/.ssh/id_rsa # your keys never entered the VM cat: /home/agent/.ssh/id_rsa: No such file or directory
$ git push # ...yet this works: ssh-agent is forwarded Enumerating objects: 5, done.
솔직히 한계를 말하자면, 허용 목록은 *알 수 없는* 서버로의 연결을 차단할 뿐, 허용한 서버를 차단하지는 않습니다. github.com은 사전 허용되어 있고 전달된 ssh-agent가 푸시할 수 있으므로, 에이전트가 읽을 수 있는 것은 무엇이든 공개할 수 있다고 간주하세요. [보안 모델](#security-model-and-its-limits)에 이 내용이 자세히 설명되어 있습니다.
그리고 에이전트가 VM을 망가뜨리면 `clawk destroy && clawk`를 실행하세요. 새 VM, 동일한 저장소, 그리고 `--resume`가 대화를 복원합니다.
> [!IMPORTANT]
> **1.0 이전 버전이며 빠르게 변화 중입니다.** 릴리스 간 호환성이 깨지는 변경과 가끔의 거친 부분이 예상됩니다. 문제가 발생할 수 있고 실제로 발생할 것입니다. 이슈를 등록해 주세요. 그 피드백이 1.0을 만들어 가고 있습니다.
## 주요 기능
- **에이전트가 무엇이든 하게 하세요.** 제한된 네트워크를 가진 일회용 VM에서 실행되므로 `rm -rf`, 패키지 설치, 신뢰할 수 없는 코드가 호스트, 파일, 또는 명시적으로 공유하지 않은 어떤 것에도 닿을 수 없습니다.
- **하나의 명령으로 작업.** 저장소로 `cd`한 후 `clawk`를 실행하세요. Dockerfile, devcontainer, 설정 파일이 필요 없습니다. 첫 부팅은 이미지에서 rootfs를 빌드하고, 이후 부팅은 몇 초면 끝납니다.
- **아무것도 잃지 않고 망가뜨리세요.** 자유롭게 파괴하고 재생성하세요. 코드와 에이전트의 대화는 호스트에 남아 있습니다. 일회용 VM 디스크만 손실됩니다.
- **진짜 Linux 머신, 당신의 툴체인.** 모든 OCI 이미지가 rootfs입니다. 프로젝트에 필요한 정확한 도구를 갖춘 완전한 OS입니다. Docker 데몬이 필요 없습니다.
- **비밀은 당신의 머신에 유지됩니다.** 외부 트래픽은 허용 목록에 있고 ssh-agent가 전달되므로 키가 VM에 들어가지 않고도 `git push`가 작동합니다.
- **프로젝트 또는 티켓별 샌드박스.** 여러 개를 동시에 실행하세요. 다중 저장소 티켓은 저장소별 git worktree를 사용하며 조정된 PR을 만듭니다. 유휴 VM은 자동으로 메모리를 해제하고 디스크에 일시 중단되므로 잊어버린 샌드박스는 (거의) 비용이 들지 않습니다.
## 왜 VM인가?
clawk는 자율 코딩 에이전트를 위한 범용 로컬 환경입니다. VM이 핵심입니다. 에이전트가 소유할 수 있는 완전한 머신이지, 당신이 사용 중인 머신에서 정책으로 감싼 프로세스가 아닙니다.
- **별도의 커널.** 게스트는 자체 Linux 커널을 실행하므로 호스트 파일시스템이 거부 규칙 뒤에 숨겨져 있는 것이 아니라 애초에 마운트된 적이 없습니다.
- **일반적인 Linux 환경.** 표준 커널, 표준 사용자 공간, `/dev/kvm` 형태의 기대치를 갖추어 도구가 문서에 설명된 대로 동작하며 syscall 필터의 예상치 못한 동작이 없습니다.
- **게스트에서의 root 권한.** 시스템 패키지 설치, `/etc` 편집, 모듈 로드, 권한 있는 포트 바인딩. 에이전트가 재구성할 수 있는 상자입니다.
- **일회용 수명 주기.** 망가뜨리기 싸고 재생성하기 빠릅니다. 망가진 VM은 `clawk destroy && clawk` 한 번이면 되며 저장소와 대화는 호스트에서 그대로 유지됩니다.
- **호스트와의 더 강력한 분리.** 격리는 프로세스 샌드박스 정책을 정확히 맞추는 것보다 하이퍼바이저 경계에 의존합니다.
이 조합은 제한된 프로세스 샌드박스가 싸우기 쉬운 워크로드를 실행합니다:
- 패키지 및 네이티브 의존성 설치;
- 백그라운드 서비스 실행(데이터베이스, 큐, 개발 서버);
- 신뢰할 수 없는 빌드와 테스트를 최대 속도로 실행;
- 실제 머신을 기대하는 시스템 수준 Linux 도구 사용;
- 그리고 지원 하드웨어에서 KVM 활성화 게스트 커널을 사용하면 Docker 또는 Kind와 같은 컨테이너 및 Kubernetes 개발 워크플로를 샌드박스 *내부에서* 실행. 이는 옵트인이며 하드웨어에 따라 제한됩니다. 정확한 요구 사항은 [이미지](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override)를 참조하세요.
이 중 어느 것도 *제품*이 아닙니다. clawk는 일반적인 로컬 에이전트 작업을 위한 것입니다. Docker와 Kubernetes는 "샌드박스 프로세스가 아닌 실제 머신이 필요하다"의 가장 날카로운 예일 뿐입니다.
## 설치
Apple 실리콘에서 macOS 14+가 필요합니다. (Linux는 firecracker를 통해 지원되며 현재 실험적입니다 — **[docs/linux-quickstart.md](https://github.com/clawkwork/clawk/blob/main/docs/linux-quickstart.md)**부터 시작하세요. 설정, 워크플로, 그리고 한계를 다룹니다. 이 README는 macOS 우선입니다.)```sh
brew install clawkwork/tap/clawk
소스에서 (기여자이거나 Homebrew를 사용하지 않는 경우), Go 1.26+가 필요합니다:```sh git clone https://github.com/clawkwork/clawk && cd clawk make install
어느 쪽이든 추가 호스트 도구는 필요 없습니다: Docker도, qemu도, sudo도 없습니다. 하이퍼바이저는 Apple의 Virtualization.framework로, 바이너리에 링크되어 있으며, 릴리스 바이너리에는 게스트 내 에이전트가 사전 빌드되어 포함되어 있습니다. 따라서 Go 툴체인은 소스에서 빌드하는 경우에만 필요하며, 그 경우에는 이미 가지고 있을 것입니다. 첫 실행 시 누락된 항목을 검사하고 수정을 제안합니다.
**제거:** `clawk destroy`로 샌드박스를 삭제하고, `rm -rf ~/.clawk`를 실행한 다음, `brew uninstall clawk`로 바이너리를 제거합니다(소스 설치의 경우 `$GOBIN`에서 삭제). 다른 것은 설치되지 않았습니다: launchd 작업이 없으며, 샌드박스별 데몬은 VM과 함께 종료되는 일반 프로세스입니다.
## 빠른 시작
일상적인 사용 사례, 현재 디렉터리를 위한 샌드박스:```sh
cd ~/code/my-project
clawk # boot a sandbox for this dir + attach claude
clawk run shell # drop into a shell in the same sandbox
clawk run codex # or another agent: codex, pi, opencode, shell
clawk down # stop the VM (repo + agent state persist)
clawk attach # come back later — boots if stopped, reattaches claude
clawk destroy # remove the VM (conversation history is kept)
공통 옵션:```sh clawk run claude -- --resume # pass args through to the agent clawk forward add my-project 3000 # expose a guest dev server on localhost:3000 clawk network allow my-project api.example.com
여러 저장소에 걸친 티켓을 작업 중이신가요? 하나의 명령으로 각 저장소에 대해 새 브랜치의 git worktree가 있는 샌드박스를 만들고, 나중에 `clawk pr`로 변경된 항목에 대한 교차 연결된 PR을 엽니다:```sh
cd ~/code/my-workspace # contains a clawk.mod listing the repos
clawk work INFRA-123 # one sandbox, a worktree per repo, claude attached
clawk pr INFRA-123 # push branches + open one PR per repo
전체 티켓 수명주기(상태, 병합 후 후속 브랜치, 리베이스)는 docs/ticket-mode.md 에 있습니다.
팁: Claude Code를 사용 중이신가요?
claude setup-token을 실행한 다음clawk auth set-token을 한 번 실행하면 모든 샌드박스가 이미 로그인된 상태로 시작되며,/login도 필요 없고 병렬 샌드박스 간 로그인 충돌도 없습니다. 자세한 내용은 docs/claude-auth.md 를 참조하세요.
하나의 규칙이 지속성을 지배합니다: VM은 일회용이며, 놓치고 싶은 모든 것은 호스트에 저장됩니다.
clawk down |
|---|
* 두 가지 예외: clawk snapshot을 재개하면 디스크와 메모리가 일시 중단된
상태 그대로 복원되며, Linux/firecracker 프로바이더는 destroy 전까지 디스크를
유지합니다. 모든 부팅에 필요한 도구는 이미지(vm ( image … ))에 포함되어야
하고, 부팅별 설정은 on up 훅에 속합니다.
에이전트 상태는 샌드박스별로 호스트에 마운트됩니다. 각 러너의 홈 디렉터리 —
claude의 ~/.claude/, codex의 ~/.codex/, pi의 ~/.pi/, opencode의 두 XDG
디렉터리 — 는 호스트의
~/.clawk/namespaces/default/state/<name>/ 아래에 있으므로, 재생성된
샌드박스는 --resume으로 이전 대화를 이어받습니다. 그 마운트가 바로 이 약속을
현실로 만드는 요소입니다. VM 디스크 자체는 부팅할 때마다 이미지에서 다시
복제되므로, 러너가 해당 디렉터리 밖에 쓴 모든 것은 다음 clawk up 시 사라집니다.
--safe 옵트아웃)러너는 "외부 샌드박스" 모드로 시작됩니다. claude는
--dangerously-skip-permissions, codex는
--dangerously-bypass-approvals-and-sandbox, pi는 --approve(승인 프롬프트가
없어 우회할 필요가 없습니다 — 샌드박스가 아예 없습니다 — 하지만 프로젝트 로컬
.pi/ 설정과 확장 프로그램은 신뢰 프롬프트 뒤에 게이트됩니다), opencode는
--auto를 받습니다. 자신의 머신에서라면 그 플래그들은 무모한 것이겠지만,
여기서는 그것이 핵심입니다. VM 경계와 네트워크 허용 목록이 격리를 제공하므로
에이전트는 작업별 프롬프트 없이 최대 속도로 작동합니다. 에이전트는 마운트하고
허용 목록에 추가한 것에만 영향을 줄 수 있으며, 그 이상은 불가능합니다
(SECURITY.md 참조).
그래도 확인 프롬프트를 선호하시나요? 모든 attach에 --safe를 추가하면
(clawk --safe, clawk run claude --safe) 해당 세션 동안 러너가 우회
플래그 없이 시작됩니다.
아웃바운드 트래픽은 기본적으로 차단되며, 각 샌드박스에는 자체 허용 목록이
있습니다. DNS는 모든 것을 해석하지만, 목록에 없는 호스트로의 TCP, UDP(QUIC
포함), ICMP 에코는 거부됩니다. 일반적인 레지스트리(npm, PyPI, crates.io,
GitHub, Anthropic 등)는 사전 허용되며, 필터는 DNS 인식 방식이므로
example.com을 허용하면 IP가 회전해도 계속 작동합니다.```sh
clawk network allow my-project api.stripe.com '*.internal.mycorp.com' 10.0.0.5
clawk network denials my-project # what the agent tried that got blocked
clawk forward add my-project 3000 # localhost:3000 → the guest's dev server
clawk forward add-reverse my-project 63342 # and the other way: a service on YOUR
# localhost, reachable inside the guest
거부는 *게스트가 확인한 호스트 이름*으로 기록되므로, `clawk network
denials`는 에이전트가 연결을 시도한 대상을 기록한 로그로 읽힙니다. 재사용 가능한 명명된
정책(외부 블록리스트(예: oisd) 구독 포함)과 이를 계층화하는
`use` 체인은
**[docs/networking.md](https://github.com/clawkwork/clawk/blob/main/docs/networking.md)**에 있습니다.
## 구성: `clawk.mod`
구성 파일은 필요하지 않습니다. 기본값이 합리적입니다. 프로젝트에 더 많은 것이 필요할 때는
`clawk.mod` 파일이 go.mod 스타일 구문으로 이를 설명합니다:```text
sandbox my-project (
vm (
cpu 4
memory 8GiB
image golang:1.25 # any OCI image is the rootfs
)
network ( allow api.example.com )
forwards ( 3000 )
env ( DATABASE_URL ) # forward a host var; values come from your shell
# also: GH=${OTHER_NAME}, LOG=${LOG:-info} defaults, API=${API:?required}
mcp ( # MCP servers, ready on first boot
linear https://mcp.linear.app/mcp header "Authorization: Bearer ${LINEAR_TOKEN}"
)
on create ( "go mod download" )
agent (
instructions "Ask before running destructive commands."
)
)
The block is a template: snapshotted when the sandbox is created, so a running sandbox never changes unexpectedly. The full reference (shares, secret files, skills, agent memory seeding, multi-repo workspace roots) is in docs/configuration.md; MCP servers and how their credentials stay off disk are in docs/mcp.md; putting a USB-serial board from your Mac inside the sandbox for microcontroller work is in docs/serial.md; images and custom guest kernels (including the KVM-enabled kernel used for nested virtualization) are in docs/images.md.
clawk list # all sandboxes clawk status [] # state, forwards, blocked hosts; --json for scripts clawk up / down # boot / stop clawk pause / resume # suspend / resume the running VM in memory clawk snapshot # save to disk: RAM freed, guest intact; resume restores it clawk destroy # remove the VM; host-side state persists
`clawk snapshot`은 샌드박스를 위한 하이버네이션입니다. 게스트의 메모리가 디스크 옆에 저장되고, 다음 부팅 시 게스트가 정확히 중단된 지점에서 복원됩니다. 백그라운드 프로세스와 개발 서버는 아무 일도 없었던 것처럼 계속 실행되며, `clawk attach`를 사용하면 에이전트 앞으로 다시 돌아갈 수 있습니다. 전체 명령어 표면, 러너 디스패치, 유휴 관리 메커니즘(벌루닝, 승인 제어, 자동 중지)은 **[docs/commands.md](https://github.com/clawkwork/clawk/blob/main/docs/commands.md)**에 있습니다.
## 작동 방식```text
you ──▶ clawk CLI ──▶ per-sandbox daemon (detached; owns the VM)
├─ gvproxy: in-process userspace TCP/IP stack —
│ the DNS-aware outbound filter the guest can't reconfigure
├─ vsock bridge to the in-guest pty-agent (no sshd)
├─ ssh-agent proxy, macOS (signing stays on the host)
└─ VM: Virtualization.framework (macOS) / firecracker (Linux)
├─ clawk-init, PID 1 (no systemd, no cloud-init)
├─ your repo, live-mounted over virtio-fs
└─ claude / codex / pi / shell on a PTY
몇 가지 의도적인 선택을 간단히 정리하면 다음과 같습니다:
clonefile / FICLONE)이므로, 샌드박스별 디스크 비용은 게스트가 쓰는 만큼만 발생합니다.전체 그림(게스트 스택, 두 공급자, 프레임 수준 네트워킹)은 **ARCHITECTURE.md**에, 각 결정의 근거는 **DESIGN.md**에 있습니다.
Dockerfile/devcontainer.json이 없습니다. 모든 OCI 이미지가 rootfs입니다.두 가지 경계가 역할을 합니다. VM(호스트 파일시스템은 마운트한 것 외에는 보이지 않음)과 아웃바운드 허용 목록(게스트 아래 사용자 공간에서 모든 프로토콜에 대해 강제 적용)입니다. clawk가 보호하지 않는 것:
files ( … ) 및 shares ( … ) 내용, 포워딩된 환경 변수, Claude 토큰은 에이전트가 읽을 수 있습니다(그리고 대상이 허용 목록에 있으면 그곳으로 보낼 수도 있습니다). 최소한만 공유하세요.경계를 깨는 방법(게스트-호스트 탈출, 네트워크 필터 우회, 자격 증명 유출)을 발견하면 SECURITY.md를 통해 비공개로 신고해 주세요.
오버헤드는 얼마인가요? 이미지의 첫 부팅은 일회성 rootfs 빌드(가져오기 → 평탄화 → ext4) 비용을 지불합니다. 이후 디스크는 copy-on-write 클론이고 커널은 펌웨어나 설치 프로그램 없이 직접 부팅됩니다. 유휴 VM은 메모리를 약 1GiB까지 해제하고, 30분 유휴 후 자동으로 중지되며, 디스크에 스냅샷을 저장하여 스토리지 비용만 발생하도록 할 수 있습니다.
Intel Mac이나 Windows에서 작동하나요? 아니요. macOS는 Apple 실리콘(macOS 14+)이 필요합니다. Linux에서는 firecracker 공급자가 작동하지만 실험적입니다(docs/commands.md 참조). Windows는 지원하지 않습니다.
Docker를 설치해야 하나요? 아니요. clawk는 OCI 이미지를 가져와 부팅 가능한 디스크를 직접 빌드합니다. Docker 이미지가 입력 형식이며, Docker 엔진은 관여하지 않습니다. (샌드박스 내부에서 Docker 데몬을 실행하는 것은 별도의 선택 기능입니다. 하드웨어 및 커널 요구 사항은 Images를 참조하세요.)
왜 "clawk"인가요? 마크는 발톱(claw)입니다. clawkwork는 *시계태엽 오렌지(A Clockwork Orange)*의 말장난입니다. 감아서 풀어놓고 언제든 리셋할 수 있는 VM이라는 뜻입니다.
다음 단계: RAM이 한 번에 담을 수 있는 것보다 더 많은 샌드박스를 실행하는 것입니다.
clawk snapshot / clawk resume으로 제공됩니다. 다음으로 자동 유휴 중지도 이를 사용하여, 개발 서버가 중지 후에도 유지되고 일시 중단된 샌드박스는 디스크 비용만 발생하도록 합니다.1.0 이전 버전이며 활발히 개발 중이고 빠르게 진화하고 있습니다. 릴리스 간에 호환성이 깨지는 변경이 있을 수 있습니다. CLI 표면은 가장 적게, 내부는 가장 많이 변경되지만, 1.0까지는 아무것도 고정되지 않습니다.
이슈와 PR을 환영합니다. 빌드 및 테스트 방법은 CONTRIBUTING.md, 빌드 방식은 ARCHITECTURE.md, 향후 방향은 DESIGN.md를 참조하세요.
Apache License 2.0. clawk는 자체 라이선스 하에 두 가지 타사 구성 요소를 포함합니다(gvisor-tap-vsock, Apache-2.0; hcsshim ext4 writer, MIT). NOTICE를 참조하세요.
clawk destroy |
|---|
| 내 저장소(마운트된 작업 트리, 커밋, 브랜치) | ✅ | ✅ |
| 에이전트 상태(Claude/Codex/pi/opencode 대화, 메모리) | ✅ | ✅ |
VM 디스크(apt 설치, 캐시, $HOME) | ❌ (부팅할 때마다 새로 재구축됨*) | ❌ (그게 핵심입니다) |