clawkwork/clawkDê aos agentes de codificação uma VM Linux descartável, não o seu laptop.
<div align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7237/193b3f67135a6e0f90c36ec914e8c5fd73a4d6181ea56b6ba75e042e6335dc72.png" alt="clawk" width="400">
*Dê a um agente de programação sua própria máquina Linux descartável, não a sua.*
[](https://github.com/clawkwork/clawk/actions/workflows/ci.yml)
[](LICENSE)
[](go.mod)
-lightgrey)
**[Instalação](#install)** · **[Início rápido](#quickstart)** ·
**[Por que uma VM?](#why-a-vm)** · **[Como funciona](#how-it-works)** ·
**[Comparado a](#compared-to)** · **[FAQ](#faq)** · **[Docs](https://github.com/clawkwork/clawk/blob/main/docs)**
</div>
Um agente de programação só é útil quando você o deixa realmente *fazer* coisas: instalar
pacotes, executar o código que escreve, iniciar servidores, usar a rede. Na sua própria
máquina, isso deixa duas opções ruins. Você aprova cada comando (e fica de babá de um
prompt a cada poucos segundos), ou executa `--dangerously-skip-permissions` e torce
para que nada importante esteja a um `rm -rf` ou a um token vazado de distância.
clawk é uma terceira opção. Faça `cd` em um repositório, digite `clawk`, e o Claude Code (ou
Codex, ou pi, ou um shell) estará trabalhando dentro de uma VM Linux descartável (seu código montado
dentro, root no guest, sem prompts de permissão) enquanto seus arquivos, seu keychain
e o resto da sua máquina permanecem fora de alcance. **O agente ganha sua própria
máquina em vez da sua.**
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7237/56b97e90b5af190abc2e1de5cc7b8ad4e835a05dd6e7a1e2f3416d78021a6a8b.gif" alt="clawk demo: clawk boots a VM and attaches claude; a blocked attempt to send data to an unknown server shows up in clawk network denials; clawk attach resumes the sandbox later" width="760">
<br>
<sub><i>Um comando para um agente funcional; uma tentativa de enviar dados para um
servidor desconhecido, bloqueada pela lista de permissões de rede; <code>clawk attach</code>
retoma a sessão depois.</i></sub>
</p>
A fronteira não é uma regra em um prompt da qual o agente poderia ser convencido a desistir. É
uma máquina separada, e as únicas aberturas são as que você montou. De um
shell dentro de um sandbox:
```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.
```
Para ser honesto sobre os limites, a lista de permissões bloqueia conexões a servidores *desconhecidos*, não aos que você permitiu: github.com é pré-permitido e o ssh-agent encaminhado pode fazer push, então trate qualquer coisa que o agente consiga ler como algo que ele poderia publicar. O [modelo de segurança](#security-model-and-its-limits) detalha isso.
E se o agente destruir a VM, execute `clawk destroy && clawk`: uma VM nova, o mesmo repositório, e `--resume` restaura a conversa.
> [!IMPORTANT]
> **Pré-1.0 e evoluindo rápido.** Espere mudanças que quebram compatibilidade entre versões e
> ocasionais arestas ásperas; as coisas podem e vão quebrar. Por favor, abra issues;
> esse feedback está moldando a 1.0.
## Destaques
- **Deixe o agente fazer qualquer coisa.** Ele roda em uma VM descartável com uma rede
restrita, então `rm -rf`, instalações de pacotes e código não confiável não conseguem alcançar seu
host, seus arquivos ou qualquer coisa que você não compartilhou explicitamente.
- **Trabalhando em um único comando.** Faça `cd` em um repositório e execute `clawk`. Sem
Dockerfile, devcontainer ou arquivo de configuração. O primeiro boot constrói um rootfs a partir
da sua imagem; cada boot seguinte leva segundos.
- **Quebre sem perder nada.** Destrua e recrie livremente; seu
código e as conversas do agente vivem no host. Apenas o disco descartável
da VM é perdido.
- **Uma máquina Linux de verdade, seu toolchain.** Qualquer imagem OCI é o rootfs: um
SO completo com exatamente as ferramentas que seu projeto precisa. Nenhum daemon Docker necessário.
- **Segredos ficam na sua máquina.** O tráfego de saída é permitido por lista e seu
ssh-agent é encaminhado, então `git push` funciona sem que chaves entrem na VM.
- **Um sandbox por projeto ou ticket.** Execute vários ao mesmo tempo; tickets multi-repo
recebem um git worktree por repositório com PRs coordenados. VMs ociosas
liberam memória automaticamente e suspendem para o disco, então um sandbox esquecido
custa (quase) nada.
## Por que uma VM?
clawk é um ambiente local de propósito geral para agentes de codificação autônomos.
A VM é o ponto central: é uma máquina inteira que o agente pode possuir, não um processo
envolto em políticas na máquina que você está usando.
- **Um kernel separado.** O guest roda seu próprio kernel Linux, então o sistema de arquivos do host
não está escondido atrás de regras de negação; ele nunca foi montado.
- **Um ambiente Linux convencional.** Kernel padrão, userland padrão,
expectativas no formato de `/dev/kvm`, então as ferramentas se comportam como suas docs dizem,
sem surpresas de filtro de syscalls.
- **Root no guest.** Instale pacotes do sistema, edite `/etc`, carregue um módulo,
faça bind em uma porta privilegiada. É a caixa do agente para reconfigurar.
- **Um ciclo de vida descartável.** Barato de quebrar e rápido de recriar; uma VM
destruída está a um `clawk destroy && clawk` de distância, com seu repositório e conversas
intactos no host.
- **Separação mais forte do host.** O isolamento repousa na fronteira do hypervisor
em vez de acertar exatamente uma política de sandbox de processo.
Essa combinação executa cargas de trabalho com as quais um sandbox de processo restrito tende a
brigar com você:
- instalar pacotes e dependências nativas;
- executar serviços em segundo plano (bancos de dados, filas, servidores de desenvolvimento);
- executar builds e testes não confiáveis em velocidade máxima;
- usar ferramentas Linux de nível de sistema que esperam uma máquina real;
- e, com um kernel guest habilitado para KVM em hardware suportado, fluxos de trabalho de desenvolvimento com contêineres e
Kubernetes, como Docker ou Kind rodando *dentro* do
sandbox. Isso é opt-in e condicionado ao hardware; veja
[Images](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override) para os requisitos exatos.
Nada disso é o *produto*; clawk é para trabalho local com agentes em geral.
Docker e Kubernetes são apenas o exemplo mais evidente de "precisa de uma máquina real,
não de um processo em sandbox."
## Instalação
Requer macOS 14+ em Apple silicon. (Linux é suportado via firecracker e
atualmente experimental — comece com
**[docs/linux-quickstart.md](https://github.com/clawkwork/clawk/blob/main/docs/linux-quickstart.md)**, que cobre a configuração,
o fluxo de trabalho e as lacunas. Este README é focado em macOS.)
```sh
brew install clawkwork/tap/clawk
```
**Do código-fonte** (contribuidores, ou se você não usa Homebrew), requer Go 1.26+:
```sh
git clone https://github.com/clawkwork/clawk && cd clawk
make install
```
De qualquer forma, não há ferramentas adicionais no host: sem Docker, sem qemu, sem sudo. O hypervisor é o Virtualization.framework da Apple, vinculado ao binário, e os binários de release trazem o agente in-guest pré-compilado — portanto, um toolchain Go só é necessário se você compilar a partir do código-fonte, caso em que você já o possui. A primeira execução verifica o que estiver faltando e oferece corrigir.
**Desinstalação:** `clawk destroy` nos seus sandboxes, `rm -rf ~/.clawk`, depois remova o binário com `brew uninstall clawk` (ou exclua-o de `$GOBIN` para uma instalação a partir do código-fonte). Nada mais foi instalado: não há jobs launchd; os daemons por sandbox são processos comuns que encerram junto com suas VMs.
## Início rápido
O caso cotidiano, um sandbox para o diretório em que você está:
```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)
```
Opções comuns:
```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
```
Trabalhando em um ticket que abrange vários repositórios? Um único comando cria um
sandbox com um git worktree por repositório em uma nova branch, e `clawk pr` depois
abre PRs cruzados para tudo o que mudou:
```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
```
O ciclo de vida completo do ticket (status, ramificações de acompanhamento após merges, rebases) está em **[docs/ticket-mode.md](https://github.com/clawkwork/clawk/blob/main/docs/ticket-mode.md)**.
> **Dica:** usando o Claude Code? Execute `claude setup-token` e depois
> `clawk auth set-token` uma vez, e cada sandbox já inicia autenticado,
> sem `/login` e sem conflitos de login entre sandboxes paralelos. Consulte
> **[docs/claude-auth.md](https://github.com/clawkwork/clawk/blob/main/docs/claude-auth.md)**.
## O que sobrevive a quê
Uma regra rege a persistência: *a VM é descartável; tudo o que você sentiria falta
vive no host.*
| | `clawk down` | `clawk destroy` |
| --- | :---: | :---: |
| Seu repositório (worktree montado; commits, branches) | ✅ | ✅ |
| Estado do agente (conversas do Claude/Codex/pi/opencode, memória) | ✅ | ✅ |
| O disco da VM (instalações via apt, caches, `$HOME`) | ❌ (recriado do zero a cada boot*) | ❌ (essa é a ideia) |
\* Duas exceções: retomar um `clawk snapshot` restaura o disco e a
memória exatamente como estavam suspensos, e o provedor Linux/firecracker mantém
seu disco até o destroy. Ferramentas necessárias a cada boot pertencem à imagem
(`vm ( image … )`); a configuração por boot pertence aos hooks `on up`.
O estado do agente é montado do host por sandbox: o diretório home de cada runner —
o `~/.claude/` do claude, o `~/.codex/` do codex, o `~/.pi/` do pi, os dois diretórios XDG do opencode — fica em
`~/.clawk/namespaces/default/state/<name>/` no host, então um sandbox recriado
recupera suas conversas antigas com `--resume`. Essa montagem é o que
torna a promessa real: o próprio disco da VM é re-clonado a partir da imagem a
cada boot, então qualquer coisa que um runner escreva fora desses diretórios se perde
no próximo `clawk up`.
## Autonomia total por padrão (e a opção de exclusão `--safe`)
Os runners iniciam em seus modos "externally sandboxed": o claude recebe
`--dangerously-skip-permissions`, o codex recebe
`--dangerously-bypass-approvals-and-sandbox`, o pi recebe `--approve` (ele não tem
prompts de aprovação para contornar — ele não traz sandbox algum — mas ele condiciona
configurações e extensões locais do projeto em `.pi/` a um prompt de confiança), e o
opencode recebe `--auto`. Na sua própria máquina essas flags
seriam imprudentes; aqui elas são o ponto: a fronteira da VM e a lista de
permissões de rede fornecem o confinamento, então o agente trabalha em velocidade máxima sem
prompts a cada ação. O agente só pode afetar o que você montou e
permitiu na lista, nada mais (consulte [SECURITY.md](https://github.com/clawkwork/clawk/blob/main/SECURITY.md)).
Prefere os prompts de confirmação de qualquer forma? Adicione `--safe` a qualquer attach
(`clawk --safe`, `clawk run claude --safe`) e o runner inicia sem suas
flags de bypass para essa sessão.
## Rede
O tráfego de saída é negado por padrão; cada sandbox tem sua própria lista de permissões.
O DNS resolve tudo; TCP, UDP (incluindo QUIC) e ICMP echo para hosts não listados
são recusados. Registries comuns (npm, PyPI, crates.io, GitHub,
Anthropic, …) são pré-permitidos, e o filtro é ciente de DNS, então permitir
`example.com` continua funcionando conforme seus IPs mudam.
```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
```
As negações são registradas pelo *hostname que o convidado resolveu*, portanto `clawk network
denials` é lido como um log do que o agente tentou acessar. Políticas nomeadas reutilizáveis (incluindo a assinatura de blocklists externas como oisd) e a cadeia `use` que as sobrepõe estão em
**[docs/networking.md](https://github.com/clawkwork/clawk/blob/main/docs/networking.md)**.
## Configuração: `clawk.mod`
Nenhum arquivo de configuração é necessário; os padrões são sensatos. Quando um projeto precisa
de mais, um arquivo `clawk.mod` o descreve, em uma sintaxe no estilo 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."
)
)
```
O bloco é um *template*: capturado no momento em que o sandbox é criado, de modo que um sandbox em execução nunca muda inesperadamente. A referência completa (shares, arquivos secretos, skills, seeding de memória do agente, raízes de workspace multi-repo) está em **[docs/configuration.md](https://github.com/clawkwork/clawk/blob/main/docs/configuration.md)**; servidores MCP e como suas credenciais permanecem fora do disco estão em **[docs/mcp.md](https://github.com/clawkwork/clawk/blob/main/docs/mcp.md)**; colocar uma placa USB-serial do seu Mac dentro do sandbox para trabalho com microcontroladores está em **[docs/serial.md](https://github.com/clawkwork/clawk/blob/main/docs/serial.md)**; imagens e kernels guest personalizados (incluindo o kernel com KVM habilitado usado para virtualização aninhada) estão em **[docs/images.md](https://github.com/clawkwork/clawk/blob/main/docs/images.md)**.
## Ciclo de vida
```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` é a hibernação para sandboxes: a memória do guest é salva
ao lado do seu disco e a próxima inicialização restaura o guest exatamente onde ele estava.
Processos em segundo plano e servidores de desenvolvimento continuam como se nada tivesse acontecido, e
`clawk attach` coloca você de volta à frente do agente. A superfície completa de comandos,
o despacho do runner e a maquinaria de gerenciamento de ociosidade (ballooning, controle de admissão, auto-stop) estão em **[docs/commands.md](https://github.com/clawkwork/clawk/blob/main/docs/commands.md)**.
## Como funciona
```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
```
Algumas escolhas deliberadas, em resumo:
- **O rootfs é uma imagem OCI comum.** O clawk a baixa (sem daemon do Docker),
achata as camadas e grava um disco ext4 diretamente, sem root e sem
dispositivos de loop. Todo sandbox da mesma imagem é um clone copy-on-write
(APFS `clonefile` / `FICLONE`), então o custo de disco por sandbox é o que o
guest grava.
- **A rede é filtrada abaixo do guest.** Todo o L3 da VM (gateway,
DHCP, DNS, NAT) é uma pilha em espaço de usuário dentro do processo do daemon. Toda
conexão de saída e resposta DNS consulta a allow-list ali, onde
nem mesmo o root dentro do guest pode alterá-la. Sem iptables no host, sem sudo.
- **Uma única via de entrada.** Sem sshd, sem cloud-init: um único agente vsock é o único
caminho de controle para dentro do guest, e cada attach é no estilo container-exec:
um processo novo, encerrado ao desconectar.
O quadro completo (a pilha do guest, ambos os provedores, a rede em nível de
frame) está em **[ARCHITECTURE.md](https://github.com/clawkwork/clawk/blob/main/ARCHITECTURE.md)**, e o raciocínio
por trás de cada decisão em **[DESIGN.md](https://github.com/clawkwork/clawk/blob/main/DESIGN.md)**.
## Comparado a
- **Containers e devcontainers.** Eles compartilham seu kernel e enxergam seu
sistema de arquivos menos as regras de negação; um único bug de kernel ou uma montagem
equivocada pode expor o host. Configurações de devcontainer frequentemente montam via bind o socket
do Docker do host para construir imagens, entregando ao container o controle do daemon do host;
o clawk mantém o Docker *dentro* da VM. E não há
`Dockerfile`/`devcontainer.json` para escrever: qualquer imagem OCI é o rootfs.
- **Sandboxes de agente em nível de SO.** Ferramentas como o sandbox-runtime da Anthropic aplicam
proteções em nível de processo na sua máquina real: ótimas para regras
leves, mas um erro de política expõe tudo (incluindo o keychain), e
instalações, serviços em segundo plano ou um hipervisor aninhado são difíceis de permitir
com segurança. O clawk move toda a carga de trabalho para uma máquina diferente.
- **Gerenciadores de VM de uso geral (ex.: Lima).** O Lima fornece uma VM Linux;
o clawk é um *workflow* em cima de uma: uma VM por projeto com o repositório
montado, um agente conectado e autenticado, egress com allow-list por
padrão e negações registradas em log, conversas do agente persistidas entre destroys,
e um modo ticket que gerencia worktrees e PRs. (Por baixo dos panos, ambos usam
Virtualization.framework.)
- **Sandboxes na nuvem.** Local-first: seu código nunca sai da máquina,
nada é cobrado por hora, e a worktree que o agente edita é a mesma
no seu editor, montada ao vivo no macOS (o provedor Linux atualmente a incorpora
na criação; veja [Roadmap](#roadmap)). Sandboxes na nuvem servem para frotas;
o clawk é para a máquina na sua mesa.
## Modelo de segurança (e seus limites)
Duas fronteiras fazem o trabalho: a VM (o sistema de arquivos do host é invisível exceto
o que você monta) e a allow-list de saída (aplicada em espaço de usuário abaixo do
guest, para todo protocolo que possa sair dele). Contra o que o clawk **não** protege:
- **Tudo o que você monta ou permite fica exposto.** As worktrees são graváveis, então um
agente pode commitar código ruim ou fazer push para qualquer repositório que seu ssh-agent encaminhado possa
alcançar. Revise o que sai de um sandbox como você revisaria o
PR de um estranho.
- **Segredos que você injeta ficam visíveis.** O conteúdo de `files ( … )` e `shares ( … )`,
variáveis de ambiente encaminhadas e o token do Claude são legíveis pelo agente
(e, se um destino estiver na allow-list, podem ser enviados para lá). Compartilhe o mínimo.
- **Escapes de hipervisor.** O clawk depende do isolamento do Virtualization.framework/KVM;
ele não adiciona defesas além deles.
Se você encontrar uma forma de quebrar uma fronteira (escape guest-to-host, bypass do filtro
de rede, vazamento de credenciais), por favor reporte de forma privada via
[SECURITY.md](https://github.com/clawkwork/clawk/blob/main/SECURITY.md).
## FAQ
**Qual é a sobrecarga?**
O primeiro boot a partir de uma imagem paga uma construção de rootfs única (pull → flatten →
ext4). Depois disso, os discos são clones copy-on-write e o kernel faz boot direto,
sem firmware e sem instalador. VMs ociosas liberam memória até ~1 GiB, param
automaticamente após 30 minutos de ociosidade, e podem ter snapshot em disco para custar
apenas armazenamento.
**Funciona em Macs Intel? Windows?**
Não. O macOS requer Apple silicon (macOS 14+). No Linux, o provedor firecracker
funciona, mas é experimental (consulte
[docs/commands.md](https://github.com/clawkwork/clawk/blob/main/docs/commands.md#vm-providers)). Não há suporte para Windows.
**Preciso ter o Docker instalado?**
Não. O clawk baixa imagens OCI e constrói discos inicializáveis por conta própria. As *imagens* Docker
são o formato de entrada; o motor do Docker não está envolvido. (Executar um daemon
Docker *dentro* de um sandbox é um recurso separado e opcional; consulte
[Images](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override) para os requisitos de hardware e kernel.)
**Por que "clawk"?**
A marca é uma garra; *clawkwork* é um trocadilho com *A Clockwork Orange*. Uma VM que você
dá corda, solta e sempre pode reiniciar.
## Roadmap
A seguir: executar mais sandboxes do que a sua RAM consegue manter ao mesmo tempo.
- **Paradas por inatividade com snapshot.** A suspensão manual para disco foi lançada como
`clawk snapshot` / `clawk resume`; em seguida, a parada por inatividade *automática* também
a utiliza, para que os servidores de desenvolvimento sobrevivam à parada e um sandbox suspenso custe apenas
disco.
- **Um limite de VMs em execução.** Em vez de recusar uma nova VM quando a RAM está
comprometida, suspender para disco o sandbox usado há menos tempo e iniciar a
nova.
- **Paridade com o Firecracker.** Propagação de worktree ao vivo e envio de arquivos do host no
Linux.
## Status
Pré-1.0 e em desenvolvimento ativo, evoluindo rapidamente: espere mudanças
incompatíveis entre versões. A superfície da CLI muda menos e os internos mais,
mas nada está congelado até a 1.0.
## Contribuindo
Issues e PRs são bem-vindos. Consulte [CONTRIBUTING.md](https://github.com/clawkwork/clawk/blob/main/CONTRIBUTING.md) para compilar
e testar, [ARCHITECTURE.md](https://github.com/clawkwork/clawk/blob/main/ARCHITECTURE.md) para saber como é construído e
[DESIGN.md](https://github.com/clawkwork/clawk/blob/main/DESIGN.md) para onde está indo.
## Licença
[Apache License 2.0](https://github.com/clawkwork/clawk/blob/main/LICENSE). O clawk inclui dois componentes de terceiros sob
suas próprias licenças (gvisor-tap-vsock, Apache-2.0; um escritor ext4 do hcsshim, MIT);
consulte [NOTICE](https://github.com/clawkwork/clawk/blob/main/NOTICE).