clawk

코딩 에이전트는 실제로 작업을 하게 할 때만 유용합니다: 패키지 설치, 작성한 코드 실행, 서버 시작, 네트워크 사용. 당신의 머신에서는 두 가지 나쁜 선택지가 남습니다. 모든 명령을 승인하거나(몇 초마다 프롬프트를 지켜봐야 함), --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 destroy
내 저장소(마운트된 작업 트리, 커밋, 브랜치)	✅	✅
에이전트 상태(Claude/Codex/pi/opencode 대화, 메모리)	✅	✅
VM 디스크(apt 설치, 캐시, $HOME)	❌ (부팅할 때마다 새로 재구축됨*)	❌ (그게 핵심입니다)

* 두 가지 예외: 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 옵트아웃)