clawk

コーディングエージェントに、あなたのマシンではなく、専用の使い捨てLinuxマシンを与えましょう。

インストール · クイックスタート · なぜVMなのか？ · 仕組み · 比較 · FAQ · ドキュメント

コーディングエージェントは、実際に何かを実行させることを許可したときだけ役に立ちます。パッケージのインストール、生成したコードの実行、サーバーの起動、ネットワークの利用などです。自分のマシンでは、これには2つの悪い選択肢しかありません。すべてのコマンドを承認する（そして数秒ごとにプロンプトを監視する）か、--dangerously-skip-permissions を実行して、重要なものが rm -rf やトークン漏洩の一歩手前でないことを祈るかです。

clawkは第三の選択肢です。リポジトリに cd して clawk と入力すると、Claude Code（またはCodex、pi、シェル）が使い捨てのLinux VM内で動作します（コードはマウントされ、ゲスト内ではroot、権限プロンプトなし）。一方、あなたのファイル、キーチェーン、その他のマシン環境には一切触れられません。エージェントはあなたのマシンではなく、専用のマシンを手に入れるのです。

_{1つのコマンドで動作するエージェントを起動; 未知のサーバーへのデータ送信の試みは、ネットワーク許可リストによってブロックされる; 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`、パッケージインストール、信頼できないコードがホスト、ファイル、明示的に共有していないものに到達することはありません。
- **1つのコマンドで動作。** リポジトリに`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

複数のリポジトリにまたがるチケットを担当していますか？1つのコマンドで、各リポジトリに新しいブランチ上の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 を参照してください。

何が何を生き残るか

永続性を支配するルールは1つです: VMは使い捨てであり、失いたくないものはすべてホスト上に置かれます。

* 例外が2つあります: clawk snapshot を再開するとディスクとメモリが中断時とまったく同じ状態に復元され、Linux/firecrackerプロバイダーはdestroyまでディスクを保持します。起動のたびに必要なツールはイメージ（vm ( image … )）に含めるべきであり、起動ごとのセットアップは on up フックに属します。

エージェントの状態はサンドボックスごとにホストにマウントされます: 各ランナーのホームディレクトリ — claudeの ~/.claude/、codexの ~/.codex/、piの ~/.pi/、opencodeの2つの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 を参照）。

それでも確認プロンプトを優先しますか？ 任意のアタッチに --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

Denials are recorded by the *hostname the guest resolved*, so `clawk network
denials` reads as a log of what the agent tried to reach. Reusable named
policies (including subscribing to external blocklists like oisd) and the
`use` chain that layers them are in
**[docs/networking.md](https://github.com/clawkwork/clawk/blob/main/docs/networking.md)**.

## Configuration: `clawk.mod`

No config file is required; defaults are sensible. When a project needs
more, a `clawk.mod` file describes it, in a go.mod-style syntax:```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.

ライフサイクル```sh

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

いくつかの意図的な選択を簡単に説明します。

• rootfsは通常のOCIイメージです。 clawkはそれを取得し（Dockerデーモンは不要）、レイヤーを平坦化して、rootやループデバイスを使わずにext4ディスクを直接書き込みます。同じイメージからの各サンドボックスはコピーオンライトのクローン（APFS clonefile / FICLONE）であり、サンドボックスごとのディスクコストはゲストが書き込む分だけです。
• ネットワークはゲストの下でフィルタリングされます。 VMのL3全体（ゲートウェイ、DHCP、DNS、NAT）は、デーモンプロセス内のユーザースペーススタックです。すべての送信接続とDNS応答はそこで許可リストを参照し、ゲスト内のrootでも変更できません。ホストのiptablesもsudoも不要です。
• 入り口は1つだけ。 sshdもcloud-initもありません。単一のvsockエージェントだけがゲストへの唯一の制御経路であり、各アタッチはcontainer-execスタイルです。つまり、新しいプロセスが起動され、切断時に破棄されます。

全体像（ゲストスタック、両プロバイダー、フレームレベルのネットワーキング）は ARCHITECTURE.md に、各決定の根拠は DESIGN.md にあります。

比較対象

• コンテナとdevcontainer。 これらはカーネルを共有し、拒否ルールを除いたファイルシステムを見ることができます。単一のカーネルバグや誤ったマウントでホストが露出する可能性があります。devcontainerのセットアップでは、イメージをビルドするためにホストのDockerソケットをバインドマウントすることが多く、コンテナにホストデーモンの制御を渡してしまいます。clawkは代わりにDockerをVMの内部に保持します。また、Dockerfile/devcontainer.jsonを書く必要もありません。任意のOCIイメージがrootfsになります。
• OSレベルのエージェントサンドボックス。 Anthropicのsandbox-runtimeのようなツールは、実際のマシン上でプロセスレベルのガードレールを適用します。軽量なルールには最適ですが、1つのポリシーミスで（キーチェーンを含む）すべてが露出し、インストール、バックグラウンドサービス、ネストされたハイパーバイザーを安全に許可するのは厄介です。clawkはワークロード全体を別のマシンに移します。
• 汎用VMマネージャー（例：Lima）。 LimaはLinux VMを提供します。clawkはその上に構築されたワークフローです。プロジェクトごとにVMがあり、リポジトリがマウントされ、エージェントがアタッチされて認証され、デフォルトで送信が許可リストに制限され、拒否がログに記録され、エージェントの会話が破棄後も保持され、worktreeとPRを管理するチケットモードがあります。（内部では両方ともVirtualization.frameworkを使用しています。）
• クラウドサンドボックス。 ローカルファースト：コードがマシンから出ることはなく、時間単位の課金もなく、エージェントが編集するworktreeはエディタにあるもので、macOSではライブマウントされます（Linuxプロバイダーは現在、作成時に組み込みます。Roadmapを参照）。クラウドサンドボックスはフリート向けです。clawkは机の上のマシン向けです。

セキュリティモデル（とその限界）

2つの境界が機能します。VM（ホストのファイルシステムは、マウントしたもの以外は見えません）と送信許可リスト（ゲストの下のユーザースペースで、そこから出られるすべてのプロトコルに対して強制されます）です。clawkが保護しないもの：

• マウントまたは許可したものはすべて露出します。 worktreeは書き込み可能なので、エージェントは悪意のあるコードをコミットしたり、転送されたssh-agentが到達できる任意のリポジトリにプッシュしたりできます。サンドボックスから出てくるものは、見知らぬ人のPRをレビューするようにレビューしてください。
• 投入したシークレットは見えます。 files ( … ) と shares ( … ) の内容、転送された環境変数、Claudeトークンはエージェントが読むことができます（宛先が許可リストに載っていれば、そこに送信することもできます）。最小限を共有してください。
• ハイパーバイザーのエスケープ。 clawkはVirtualization.framework/KVMの分離に依存しています。それらを超える防御は追加しません。

境界を破る方法（ゲストからホストへのエスケープ、ネットワークフィルターのバイパス、資格情報の漏洩）を見つけた場合は、SECURITY.md を通じて非公開で報告してください。

FAQ

オーバーヘッドはどのくらいですか？ イメージからの初回起動では、一度だけrootfsのビルド（取得 → 平坦化 → ext4）が行われます。その後、ディスクはコピーオンライトのクローンで、カーネルはファームウェアもインストーラーもなしで直接起動します。アイドル状態のVMはメモリを約1 GiBまで解放し、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という意味です。

Roadmap

次は、RAMに収まらない数のサンドボックスを同時に実行することです。

• スナップショット付きアイドル停止。 手動のサスペンド・トゥ・ディスクが clawk snapshot / clawk resume として提供されます。次に、自動アイドル停止もこれを使用し、開発サーバーが停止後も存続し、サスペンドされたサンドボックスはディスクのみのコストになります。
• 実行中VMの上限。 RAMがコミットされているときに新しいVMを拒否する代わりに、最も最近使用されていないサンドボックスをディスクにサスペンドして、新しいものを起動します。
• Firecrackerのパリティ。 Linuxでのライブworktree伝播とホストファイルのプッシュ。

ステータス

1.0未満で活発に開発中であり、急速に進化しています。リリース間で破壊的な変更が予想されます。CLIの表面は最も変更が少なく、内部が最も変更されますが、1.0まで凍結されるものはありません。

貢献

IssueとPRを歓迎します。ビルドとテストについてはCONTRIBUTING.md、構築方法についてはARCHITECTURE.md、今後の方向性についてはDESIGN.mdを参照してください。

ライセンス

Apache License 2.0。clawkは、独自のライセンスの下で2つのサードパーティコンポーネントをベンダー提供しています（gvisor-tap-vsock、Apache-2.0；hcsshim ext4ライター、MIT）。NOTICEを参照してください。