clawk v0.4.0

Дайте агентy для написания кода его собственную одноразовую Linux-машину, а не вашу.

Установка · Быстрый старт · Зачем виртуальная машина? · Как это работает · Сравнение · FAQ · Документация

Агент для написания кода полезен только тогда, когда вы позволяете ему реально делать вещи: устанавливать пакеты, запускать написанный им код, поднимать серверы, пользоваться сетью. На вашей собственной машине это оставляет два плохих варианта. Вы одобряете каждую команду (и нянчитесь с запросом каждые несколько секунд), либо запускаете --dangerously-skip-permissions и надеетесь, что ничего важного не окажется в одном rm -rf или одной утёкшей токен-строке.

clawk — это третий вариант. cd в репозиторий, введите clawk, и Claude Code (или Codex, или pi, или оболочка) работает внутри одноразовой Linux-виртуальной машины (ваш код смонтирован внутрь, 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.

Чтобы быть честным в отношении ограничений: 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.

Совет: используете Claude Code? Выполните claude setup-token, затем clawk auth set-token один раз — и каждая песочница будет запускаться уже авторизованной, без /login и без конфликтов входа между параллельными песочницами. См. docs/claude-auth.md.

Что переживает что

Одно правило управляет сохранностью: ВМ одноразовая; всё, что вам дорого, живёт на хосте.

* Два исключения: возобновление 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).

Всё же предпочитаете запросы на подтверждение? Добавьте --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; MCP-серверы и то, как их учётные данные не сохраняются на диске, описаны в docs/mcp.md; подключение USB-последовательной платы с вашего Mac внутри песочницы для работы с микроконтроллерами описано в docs/serial.md; образы и пользовательские ядра гостевой системы (включая ядро с поддержкой KVM, используемое для вложенной виртуализации) находятся в 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` — это гибернация для песочниц: память гостя сохраняется
рядом с его диском, и при следующей загрузке гость восстанавливается ровно в том состоянии, где он был.
Фоновые процессы и 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, а обоснование каждого решения — в 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). Облачные песочницы подходят для флотов; clawk — для машины на вашем столе.

Модель безопасности (и её ограничения)

Работу выполняют две границы: виртуальная машина (файловая система хоста невидима, кроме того, что вы монтируете) и исходящий allow-лист (применяется в userspace ниже гостевой системы, для каждого протокола, который может её покинуть). От чего clawk не защищает:

• Всё, что вы монтируете или разрешаете, открыто. Worktree доступны на запись, поэтому агент может закоммитить плохой код или запушить в любой репозиторий, доступный вашему форварднутому ssh-agent. Проверяйте то, что выходит из песочницы, как вы бы проверяли PR незнакомца.
• Секреты, которые вы передаёте внутрь, видны. Содержимое files ( … ) и shares ( … ), форварднутые переменные окружения и токен Claude доступны агенту для чтения (и, если пункт назначения в allow-листе, для отправки туда). Делитесь минимумом.
• Побеги из гипервизора. clawk полагается на изоляцию Virtualization.framework/KVM; он не добавляет защиту сверх неё.

Если вы найдёте способ нарушить границу (побег гость-хост, обход сетевого фильтра, утечку учётных данных), пожалуйста, сообщите об этом конфиденциально через SECURITY.md.

FAQ

Каковы накладные расходы? Первый запуск из образа оплачивает разовую сборку rootfs (pull → flatten → ext4). После этого диски — это copy-on-write клоны, а ядро загружается напрямую, без прошивки и без установщика. Простаивающие VM освобождают память до ~1 ГиБ, автоматически останавливаются после 30 минут простоя и могут быть сняты в снапшот на диск, так что стоят только хранение.

Работает ли на Intel Mac? Windows? Нет. Для macOS нужен Apple silicon (macOS 14+). На Linux провайдер firecracker работает, но экспериментален (см. docs/commands.md). Поддержки Windows нет.

Нужно ли устанавливать Docker? Нет. clawk сам загружает OCI-образы и собирает загрузочные диски. Docker образы — это входной формат; движок Docker не задействован. (Запуск Docker-демона внутри песочницы — это отдельная, опциональная функция; см. Images для требований к оборудованию и ядру.)

Почему «clawk»? Метка — это коготь; clawkwork — игра слов с A Clockwork Orange. VM, которую вы заводите, отпускаете и всегда можете сбросить.

Roadmap

Дальше: запуск большего числа песочниц, чем может вместить ваша RAM.

• Остановки простоя со снапшотом. Ручная приостановка на диск реализована как clawk snapshot / clawk resume; далее автоматическая остановка простоя тоже будет её использовать, чтобы dev-серверы переживали остановку, а приостановленная песочница стоила только диск.
• Лимит на запущенные VM. Вместо отказа новой VM при нехватке RAM — приостановка наименее используемой песочницы на диск и запуск новой.
• Паритет с Firecracker. Живое распространение worktree и отправка файлов на хост на Linux.

Статус

Pre-1.0 и в активной разработке, развивается быстро: ожидайте ломающих изменений между релизами. CLI-поверхность меняется меньше всего, внутренности — больше всего, но ничего не заморожено до 1.0.

Вклад

Приветствуются issues и PR. См. CONTRIBUTING.md для сборки и тестирования, ARCHITECTURE.md — как это устроено, и DESIGN.md — куда это движется.

Лицензия

Apache License 2.0. clawk включает два сторонних компонента под их собственными лицензиями (gvisor-tap-vsock, Apache-2.0; ext4-писатель из hcsshim, MIT); см. NOTICE.