clawkwork/clawkДайте агентам кодирования одноразовую Linux VM, а не ваш ноутбук
<div align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7237/193b3f67135a6e0f90c36ec914e8c5fd73a4d6181ea56b6ba75e042e6335dc72.png" alt="clawk" width="400">
*Дайте агентy для написания кода его собственную одноразовую Linux-машину, а не вашу.*
[](https://github.com/clawkwork/clawk/actions/workflows/ci.yml)
[](LICENSE)
[](go.mod)
-lightgrey)
**[Установка](#install)** · **[Быстрый старт](#quickstart)** ·
**[Зачем виртуальная машина?](#why-a-vm)** · **[Как это работает](#how-it-works)** ·
**[Сравнение](#compared-to)** · **[FAQ](#faq)** · **[Документация](https://github.com/clawkwork/clawk/blob/main/docs)**
</div>
Агент для написания кода полезен только тогда, когда вы позволяете ему реально *делать* вещи: устанавливать пакеты, запускать написанный им код, поднимать серверы, пользоваться сетью. На вашей собственной машине это оставляет два плохих варианта. Вы одобряете каждую команду (и нянчитесь с запросом каждые несколько секунд), либо запускаете `--dangerously-skip-permissions` и надеетесь, что ничего важного не окажется в одном `rm -rf` или одной утёкшей токен-строке.
clawk — это третий вариант. `cd` в репозиторий, введите `clawk`, и Claude Code (или Codex, или pi, или оболочка) работает внутри одноразовой Linux-виртуальной машины (ваш код смонтирован внутрь, root в гостевой системе, без запросов на разрешения), пока ваши файлы, ваша связка ключей и остальная часть вашей машины остаются вне досягаемости. **Агент получает собственную машину вместо вашей.**
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7237/56b97e90b5af190abc2e1de5cc7b8ad4e835a05dd6e7a1e2f3416d78021a6a8b.gif" alt="clawk demo: clawk загружает виртуальную машину и подключает claude; заблокированная попытка отправить данные на неизвестный сервер отображается в сетевых отказах clawk; clawk attach возобновляет песочницу позже" width="760">
<br>
<sub><i>Одна команда до работающего агента; попытка отправить данные на
неизвестный сервер, заблокированная сетевым белым списком; <code>clawk attach</code>
возобновляет сеанс позже.</i></sub>
</p>
Граница — это не правило в промпте, от которого агента можно отговорить. Это отдельная машина, и единственные отверстия — те, что вы смонтировали. Из оболочки внутри песочницы:```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.
```
Чтобы быть честным в отношении ограничений: allow-list блокирует соединения с *неизвестными*
серверами, а не с теми, которые вы разрешили: github.com предварительно разрешён, и
проброшенный ssh-agent может выполнять push, поэтому считайте, что всё, что агент может прочитать,
он может и опубликовать. В
[модели безопасности](#security-model-and-its-limits) это подробно описано.
А если агент сломает ВМ, выполните `clawk destroy && clawk`: новая ВМ, тот же
репозиторий, а `--resume` восстановит разговор.
> [!IMPORTANT]
> **До версии 1.0 и быстрое развитие.** Ожидайте ломающих изменений между релизами и
> иногда шероховатостей; что-то может и будет ломаться. Пожалуйста, создавайте issues;
> именно эта обратная связь формирует версию 1.0.
## Ключевые возможности
- **Позвольте агенту делать что угодно.** Он работает в одноразовой ВМ с ограниченной
сетью, поэтому `rm -rf`, установка пакетов и недоверенный код не могут добраться до вашего
хоста, ваших файлов или чего-либо, чем вы явно не поделились.
- **Работа одной командой.** Выполните `cd` в репозиторий и запустите `clawk`. Никакого
Dockerfile, devcontainer или файла настройки. Первая загрузка собирает rootfs из
вашего образа; каждая последующая загрузка занимает секунды.
- **Ломайте без потерь.** Уничтожайте и пересоздавайте свободно; ваш
код и разговоры агента хранятся на хосте. Теряется только диск одноразовой ВМ.
- **Настоящий Linux-бокс, ваш инструментарий.** Любой OCI-образ — это rootfs: полноценная
ОС ровно с теми инструментами, которые нужны вашему проекту. Демон Docker не требуется.
- **Секреты остаются на вашей машине.** Исходящий трафик ограничен allow-list, а ваш
ssh-agent пробрасывается, поэтому `git push` работает без попадания ключей в ВМ.
- **Песочница на проект или задачу.** Запускайте несколько одновременно; для задач
с несколькими репозиториями создаётся git worktree на каждый репозиторий со скоординированными PR.
Простаивающие ВМ автоматически освобождают память и приостанавливаются на диск, поэтому забытая
песочница стоит (почти) ничего.
## Зачем ВМ?
clawk — это универсальное локальное окружение для автономных агентов кодирования.
Суть именно в ВМ: это целая машина, которой агент владеет, а не процесс,
обёрнутый в политики на той машине, которую используете вы.
- **Отдельное ядро.** Гостевая система запускает собственное ядро Linux, поэтому
файловая система хоста не скрыта за правилами запрета; она вообще никогда не монтировалась.
- **Привычное окружение Linux.** Стандартное ядро, стандартное пользовательское пространство,
ожидания в духе `/dev/kvm` — инструменты ведут себя так, как описано в их документации,
без сюрпризов от фильтрации системных вызовов.
- **Root в гостевой системе.** Устанавливайте системные пакеты, редактируйте `/etc`, загружайте модуль,
привязывайте привилегированный порт. Это машина агента, и он может её перенастраивать.
- **Одноразовый жизненный цикл.** Дешёво сломать и быстро пересоздать; разбитая
ВМ — это один `clawk destroy && clawk`, а ваш репозиторий и разговоры
остаются нетронутыми на хосте.
- **Более сильная изоляция от хоста.** Изоляция опирается на границу гипервизора,
а не на идеально выверенную политику песочницы процессов.
Такое сочетание выполняет рабочие нагрузки, с которыми ограниченная песочница процессов обычно
борется:
- установка пакетов и нативных зависимостей;
- запуск фоновых сервисов (базы данных, очереди, dev-серверы);
- выполнение недоверенных сборок и тестов на полной скорости;
- использование системных Linux-инструментов, которые ожидают реальную машину;
- и, с гостевым ядром с поддержкой KVM на поддерживаемом оборудовании, dev-процессы
с контейнерами и Kubernetes, такие как Docker или Kind, работающие *внутри*
песочницы. Это опционально и зависит от оборудования; точные требования см. в
[Images](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override).
Ничто из этого не является *продуктом*; clawk предназначен для локальной работы агентов в целом.
Docker и Kubernetes — просто самый яркий пример «нужна реальная машина,
а не песочница процессов».
## Установка
Требуется macOS 14+ на Apple silicon. (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; демоны каждой песочницы — это обычные процессы, которые завершаются вместе со своими виртуальными машинами.
## Быстрый старт
Самый частый случай — песочница для текущей директории:```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](https://github.com/clawkwork/clawk/blob/main/docs/ticket-mode.md)**.
> **Совет:** используете Claude Code? Выполните `claude setup-token`, затем
> `clawk auth set-token` один раз — и каждая песочница будет запускаться уже
> авторизованной, без `/login` и без конфликтов входа между параллельными
> песочницами. См. **[docs/claude-auth.md](https://github.com/clawkwork/clawk/blob/main/docs/claude-auth.md)**.
## Что переживает что
Одно правило управляет сохранностью: *ВМ одноразовая; всё, что вам дорого,
живёт на хосте.*
| | `clawk down` | `clawk destroy` |
| --- | :---: | :---: |
| Ваш репозиторий (смонтированное рабочее дерево; коммиты, ветки) | ✅ | ✅ |
| Состояние агента (разговоры Claude/Codex/pi/opencode, память) | ✅ | ✅ |
| Диск ВМ (установки apt, кэши, `$HOME`) | ❌ (пересоздаётся заново при каждой загрузке*) | ❌ (в этом и смысл) |
\* Два исключения: возобновление `clawk snapshot` восстанавливает диск и
память точно в том виде, в каком они были при приостановке, а провайдер
Linux/firecracker сохраняет свой диск до destroy. Инструменты, нужные при
каждой загрузке, должны быть в образе (`vm ( image … )`); настройка на
каждую загрузку — в хуках `on up`.
Состояние агента монтируется на хосте для каждой песочницы: домашний каталог
каждого раннера — `~/.claude/` у claude, `~/.codex/` у codex, `~/.pi/` у pi,
два XDG-каталога у opencode — находятся в
`~/.clawk/namespaces/default/state/<name>/` на хосте, поэтому пересозданная
песочница подхватывает свои старые разговоры с помощью `--resume`. Именно
этот монтирование делает обещание реальным: сам диск ВМ заново клонируется
из образа при каждой загрузке, так что всё, что раннер записывает вне этих
каталогов, исчезает при следующем `clawk up`.
## Полная автономия по умолчанию (и отказ через `--safe`)
Раннеры запускаются в своих «внешне изолированных» режимах: claude получает
`--dangerously-skip-permissions`, codex получает
`--dangerously-bypass-approvals-and-sandbox`, pi получает `--approve` (у него
нет запросов на подтверждение, которые можно обойти, — он вообще не
поставляется с песочницей, — но он блокирует локальные для проекта настройки
`.pi/` и расширения за запросом доверия), а opencode получает `--auto`. На
собственной машине эти флаги были бы безрассудством; здесь они и есть суть:
граница ВМ и сетевой список разрешений обеспечивают изоляцию, поэтому агент
работает на полной скорости без запросов на каждое действие. Агент может
воздействовать только на то, что вы смонтировали и внесли в список
разрешений, и ни на что больше (см. [SECURITY.md](https://github.com/clawkwork/clawk/blob/main/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 записываются по *имени хоста, которое разрешил гость*, поэтому `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."
)
)
```
Блок является *шаблоном*: он фиксируется при создании песочницы, поэтому
работающая песочница никогда не меняется неожиданно. Полная документация (общие ресурсы,
секретные файлы, навыки, начальное заполнение памяти агента, корни рабочих областей с несколькими репозиториями)
находится в **[docs/configuration.md](https://github.com/clawkwork/clawk/blob/main/docs/configuration.md)**; MCP-серверы и то, как
их учётные данные не сохраняются на диске, описаны в **[docs/mcp.md](https://github.com/clawkwork/clawk/blob/main/docs/mcp.md)**;
подключение USB-последовательной платы с вашего Mac внутри песочницы для
работы с микроконтроллерами описано в **[docs/serial.md](https://github.com/clawkwork/clawk/blob/main/docs/serial.md)**; образы
и пользовательские ядра гостевой системы (включая ядро с поддержкой KVM, используемое для вложенной
виртуализации) находятся в **[docs/images.md](https://github.com/clawkwork/clawk/blob/main/docs/images.md)**.
## Жизненный цикл```sh
clawk list # all sandboxes
clawk status [<name>] # 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` — это гибернация для песочниц: память гостя сохраняется
рядом с его диском, и при следующей загрузке гость восстанавливается ровно в том состоянии, где он был.
Фоновые процессы и dev-серверы продолжают работать, как будто ничего не произошло, а
`clawk attach` возвращает вас к агенту. Полная поверхность команд,
диспетчеризация раннеров и механизмы управления простоем (ballooning, admission
control, auto-stop) описаны в **[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-демона), разворачивает слои и записывает ext4-диск напрямую, без root и без loop-устройств. Каждая песочница из одного образа — это copy-on-write клон (APFS `clonefile` / `FICLONE`), поэтому стоимость диска на песочницу — это то, что записывает гостевая система.
- **Сеть фильтруется ниже гостевой системы.** Весь L3 виртуальной машины (шлюз, DHCP, DNS, NAT) — это userspace-стек внутри процесса демона. Каждое исходящее соединение и DNS-ответ проверяются по allow-списку там, где даже root внутри гостевой системы не может его изменить. Никаких host-iptables, никакого sudo.
- **Один путь внутрь.** Ни sshd, ни cloud-init: единственный канал управления гостем — это один vsock-агент, и каждое подключение работает в стиле container-exec: новый процесс, который завершается при отключении.
Полная картина (гостевой стек, оба провайдера, сеть на уровне кадров) — в **[ARCHITECTURE.md](https://github.com/clawkwork/clawk/blob/main/ARCHITECTURE.md)**, а обоснование каждого решения — в **[DESIGN.md](https://github.com/clawkwork/clawk/blob/main/DESIGN.md)**.
## По сравнению с
- **Контейнерами и devcontainer.** Они разделяют ваше ядро и видят вашу файловую систему за вычетом deny-правил; одна ошибка ядра или неудачный mount может открыть доступ к хосту. Настройки devcontainer часто монтируют host-сокет Docker для сборки образов, отдавая контейнеру контроль над демоном хоста; clawk вместо этого держит Docker *внутри* виртуальной машины. И не нужно писать `Dockerfile`/`devcontainer.json`: любой OCI-образ — это rootfs.
- **Песочницами на уровне ОС.** Такие инструменты, как sandbox-runtime от Anthropic, применяют guardrails на уровне процессов на вашей реальной машине: отлично для лёгких правил, но одна ошибка в политике открывает всё (включая связку ключей), а установки, фоновые сервисы или вложенный гипервизор сложно разрешить безопасно. clawk переносит всю рабочую нагрузку на другую машину.
- **Универсальными менеджерами виртуальных машин (например, Lima).** Lima даёт вам Linux-VM; clawk — это *рабочий процесс* поверх неё: VM на проект с смонтированным репозиторием, подключённым и аутентифицированным агентом, egress, разрешённый по умолчанию через allow-лист и логирующий отказы, сессии агента, сохраняемые между уничтожениями, и режим тикетов, управляющий worktree и PR. (Под капотом оба используют Virtualization.framework.)
- **Облачными песочницами.** Локально-ориентированный подход: ваш код никогда не покидает машину, ничего не тарифицируется по часам, а worktree, который редактирует агент, — это тот, что в вашем редакторе, live-смонтированный на macOS (Linux-провайдер на данный момент встраивает его при создании; см. [Roadmap](#roadmap)). Облачные песочницы подходят для флотов; clawk — для машины на вашем столе.
## Модель безопасности (и её ограничения)
Работу выполняют две границы: виртуальная машина (файловая система хоста невидима, кроме того, что вы монтируете) и исходящий allow-лист (применяется в userspace ниже гостевой системы, для каждого протокола, который может её покинуть). От чего clawk **не** защищает:
- **Всё, что вы монтируете или разрешаете, открыто.** Worktree доступны на запись, поэтому агент может закоммитить плохой код или запушить в любой репозиторий, доступный вашему форварднутому ssh-agent. Проверяйте то, что выходит из песочницы, как вы бы проверяли PR незнакомца.
- **Секреты, которые вы передаёте внутрь, видны.** Содержимое `files ( … )` и `shares ( … )`, форварднутые переменные окружения и токен Claude доступны агенту для чтения (и, если пункт назначения в allow-листе, для отправки туда). Делитесь минимумом.
- **Побеги из гипервизора.** clawk полагается на изоляцию Virtualization.framework/KVM; он не добавляет защиту сверх неё.
Если вы найдёте способ нарушить границу (побег гость-хост, обход сетевого фильтра, утечку учётных данных), пожалуйста, сообщите об этом конфиденциально через [SECURITY.md](https://github.com/clawkwork/clawk/blob/main/SECURITY.md).
## FAQ
**Каковы накладные расходы?**
---
[Read more](https://github.com/clawkwork/clawk)