clawk v0.4.0

Dai all'agente di coding una sua macchina Linux usa e getta, non la tua.

Installazione · Avvio rapido · Perché una VM? · Come funziona · Confronto · FAQ · Documentazione

Un agente di coding è utile solo se gli permetti davvero di fare cose: installare pacchetti, eseguire il codice che scrive, avviare server, usare la rete. Sulla tua macchina questo lascia due brutte opzioni. Approvi ogni comando (e fai da babysitter a un prompt ogni pochi secondi), oppure esegui --dangerously-skip-permissions e speri che nulla di importante sia a un solo rm -rf o a un solo token trapelato di distanza.

clawk è una terza opzione. Fai cd in una repo, digita clawk, e Claude Code (o Codex, o pi, o una shell) lavora dentro una VM Linux usa e getta (il tuo codice montato dentro, root nell'ospite, nessun prompt di permessi) mentre i tuoi file, il tuo portachiavi e il resto della tua macchina restano fuori portata. L'agente ha la sua macchina invece della tua.

_{Un comando per un agente operativo; un tentativo di inviare dati a un server sconosciuto, bloccato dalla allow-list di rete; clawk attach riprende la sessione più tardi.}

Il confine non è una regola in un prompt da cui l'agente potrebbe essere convinto a uscire. È una macchina separata, e le uniche aperture sono quelle che hai montato tu. Da una shell dentro una 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.

Per essere onesti sui limiti, la lista consentita blocca le connessioni a server *sconosciuti*, non a quelli che hai consentito: github.com è pre-consentito e l'agent ssh inoltrato può eseguire push, quindi tratta qualsiasi cosa l'agent possa leggere come qualcosa che potrebbe pubblicare. Il [modello di sicurezza](#security-model-and-its-limits) lo spiega nel dettaglio.

E se l'agent distrugge la VM, esegui `clawk destroy && clawk`: una VM nuova, stesso repo, e `--resume` ripristina la conversazione.

> [!IMPORTANT]
> **Pre-1.0 e in rapida evoluzione.** Aspettati modifiche che rompono la compatibilità tra le release e qualche spigolo occasionale; le cose possono e andranno in tilt. Per favore apri issue; quel feedback sta plasmando la 1.0.

## Punti salienti

- **Lascia che l'agent faccia qualsiasi cosa.** Gira in una VM usa-e-getta con rete limitata, quindi `rm -rf`, installazioni di pacchetti e codice non fidato non possono raggiungere il tuo host, i tuoi file o qualsiasi cosa tu non abbia condiviso esplicitamente.
- **Lavorare con un solo comando.** Fai `cd` in un repo ed esegui `clawk`. Niente Dockerfile, devcontainer o file di setup. Il primo avvio costruisce un rootfs dalla tua immagine; ogni avvio successivo richiede secondi.
- **Rompi tutto senza perdere nulla.** Distruggi e ricrea liberamente; il tuo codice e le conversazioni dell'agent vivono sull'host. Solo il disco della VM usa-e-getta viene perso.
- **Una vera macchina Linux, la tua toolchain.** Qualsiasi immagine OCI è il rootfs: un sistema operativo completo con esattamente gli strumenti di cui il tuo progetto ha bisogno. Nessun daemon Docker richiesto.
- **I segreti restano sulla tua macchina.** Il traffico in uscita è in lista consentita e il tuo ssh-agent viene inoltrato, quindi `git push` funziona senza che le chiavi entrino nella VM.
- **Una sandbox per progetto o ticket.** Eseguine diverse contemporaneamente; i ticket multi-repo ottengono un git worktree per repo con PR coordinate. Le VM inattive rilasciano automaticamente la memoria e si sospendono su disco, quindi una sandbox dimenticata costa (quasi) nulla.

## Perché una VM?

clawk è un ambiente locale generico per agenti di codifica autonomi. La VM è il punto: è una macchina intera che l'agent può possedere, non un processo avvolto in policy su quella che stai usando tu.

- **Un kernel separato.** L'ospite esegue il proprio kernel Linux, quindi il filesystem dell'host non è nascosto dietro regole di negazione; non è mai stato montato.
- **Un ambiente Linux convenzionale.** Kernel standard, userland standard, aspettative a forma di `/dev/kvm`, così gli strumenti si comportano come dicono i loro documenti, senza sorprese da filtro syscall.
- **Root nell'ospite.** Installa pacchetti di sistema, modifica `/etc`, carica un modulo, vincola una porta privilegiata. È la scatola dell'agent da riconfigurare.
- **Un ciclo di vita usa-e-getta.** Economico da rompere e veloce da ricreare; una VM distrutta è a un `clawk destroy && clawk` di distanza, con il tuo repo e le conversazioni intatti sull'host.
- **Separazione più forte dall'host.** L'isolamento si basa sul confine dell'hypervisor piuttosto che sull'azzeccare perfettamente una policy di sandbox per processi.

Quella combinazione esegue carichi di lavoro su cui una sandbox per processi limitata tende a farti combattere:

- installare pacchetti e dipendenze native;
- eseguire servizi in background (database, code, server di sviluppo);
- eseguire build e test non fidati a piena velocità;
- usare tooling Linux di sistema che si aspetta una macchina reale;
- e, con un kernel ospite abilitato a KVM su hardware supportato, flussi di lavoro di sviluppo container e Kubernetes come Docker o Kind che girano *dentro* la sandbox. Questo è opt-in e limitato dall'hardware; vedi [Immagini](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override) per i requisiti esatti.

Niente di tutto questo è il *prodotto*; clawk è per lavoro locale con agenti in generale. Docker e Kubernetes sono solo l'esempio più calzante di "serve una macchina reale, non un processo in sandbox".

## Installazione

Richiede macOS 14+ su Apple silicon. (Linux è supportato tramite firecracker e attualmente sperimentale — inizia con **[docs/linux-quickstart.md](https://github.com/clawkwork/clawk/blob/main/docs/linux-quickstart.md)**, che copre il setup, il flusso di lavoro e le lacune. Questo README è incentrato su macOS.)```sh
brew install clawkwork/tap/clawk

Dalla sorgente (contributori, o se non usi Homebrew), serve Go 1.26+:```sh git clone https://github.com/clawkwork/clawk && cd clawk make install

In ogni caso non c'è tooling host aggiuntivo: niente Docker, niente qemu, niente sudo. L'hypervisor è il Virtualization.framework di Apple, collegato direttamente nel binario, e i binari di release includono l'agente in-guest già precompilato — quindi una toolchain Go serve solo se compili dal sorgente, e in quel caso ce l'hai già. Il primo avvio verifica se manca qualcosa e offre di sistemarlo.

**Disinstallazione:** `clawk destroy` per eliminare le tue sandbox, `rm -rf ~/.clawk`, poi rimuovi il binario con `brew uninstall clawk` (oppure cancellalo da `$GOBIN` per un'installazione da sorgente). Non è stato installato nient'altro: non ci sono job launchd; i daemon per-sandbox sono processi ordinari che terminano insieme alle loro VM.

## Avvio rapido

Il caso d'uso quotidiano, una sandbox per la directory in cui ti trovi:```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)

Opzioni comuni:```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

Lavori su un ticket che coinvolge più repository? Un solo comando crea una
sandbox con un git worktree per ogni repo su un nuovo branch, e `clawk pr` in seguito
apre PR cross-linkate per tutto ciò che è cambiato:```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

Il ciclo di vita completo dei ticket (stato, rami di follow-up dopo i merge, rebase) è descritto in docs/ticket-mode.md.

Suggerimento: usi Claude Code? Esegui claude setup-token e poi clawk auth set-token una sola volta, e ogni sandbox si avvierà già autenticata, senza /login e senza conflitti di login tra sandbox parallele. Vedi docs/claude-auth.md.

Cosa sopravvive a cosa

Una sola regola governa la persistenza: la VM è usa-e-getta; tutto ciò che ti mancherebbe vive sull'host.

* Due eccezioni: riprendere uno clawk snapshot ripristina il disco e la memoria esattamente come sospesi, e il provider Linux/firecracker mantiene il proprio disco fino a destroy. Gli strumenti necessari a ogni avvio appartengono all'immagine (vm ( image … )); la configurazione per ogni avvio appartiene agli hook on up.

Lo stato dell'agente è montato sull'host per ogni sandbox: la home directory di ogni runner — ~/.claude/ di claude, ~/.codex/ di codex, ~/.pi/ di pi, le due directory XDG di opencode — si trovano sotto ~/.clawk/namespaces/default/state/<name>/ sull'host, quindi una sandbox ricreata riprende le sue vecchie conversazioni con --resume. Quel mount è ciò che rende reale la promessa: il disco della VM viene re-clonato dall'immagine a ogni avvio, quindi qualsiasi cosa un runner scriva al di fuori di quelle directory sparisce al successivo clawk up.

Piena autonomia di default (e l'opt-out --safe)

I runner si avviano nelle loro modalità "sandbox esterna": claude riceve --dangerously-skip-permissions, codex riceve --dangerously-bypass-approvals-and-sandbox, pi riceve --approve (non ha prompt di approvazione da bypassare — non include alcuna sandbox — ma blocca comunque le impostazioni e le estensioni .pi/ locali al progetto dietro un prompt di fiducia), e opencode riceve --auto. Sulla tua macchina quei flag sarebbero avventati; qui sono il punto: il confine della VM e la allow-list di rete forniscono il contenimento, così l'agente lavora a piena velocità senza prompt per ogni azione. L'agente può influenzare solo ciò che hai montato e inserito in allow-list, niente di più (vedi SECURITY.md).

Preferisci comunque i prompt di conferma? Aggiungi --safe a qualsiasi attach (clawk --safe, clawk run claude --safe) e il runner si avvia senza i suoi flag di bypass per quella sessione.

Rete

Il traffico in uscita è negato di default; ogni sandbox ha la propria allow-list. Il DNS risolve tutto; TCP, UDP (incluso QUIC) e ICMP echo verso host non elencati vengono rifiutati. I registry comuni (npm, PyPI, crates.io, GitHub, Anthropic, …) sono pre-consentiti, e il filtro è consapevole del DNS, quindi consentire example.com continua a funzionare mentre i suoi IP ruotano.```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."
    )
)

Il blocco è un template: viene catturato come snapshot quando la sandbox viene creata, quindi una sandbox in esecuzione non cambia mai inaspettatamente. Il riferimento completo (share, file segreti, skill, seeding della memoria dell'agente, root di workspace multi-repo) è in docs/configuration.md; i server MCP e come le loro credenziali restano fuori dal disco sono in docs/mcp.md; inserire una scheda USB-serial dal tuo Mac all'interno della sandbox per lavoro su microcontrollori è in docs/serial.md; le immagini e i kernel guest personalizzati (incluso il kernel abilitato a KVM usato per la virtualizzazione annidata) sono in docs/images.md.

Ciclo di vita```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` è l'ibernazione per le sandbox: la memoria dell'ospite viene salvata
accanto al suo disco e il successivo avvio ripristina l'ospite esattamente dove era.
I processi in background e i server di sviluppo continuano come se nulla fosse, e
`clawk attach` ti riporta davanti all'agente. L'intera superficie dei comandi,
l'invio dei runner e la gestione dell'idle (ballooning, admission
control, auto-stop) sono in **[docs/commands.md](https://github.com/clawkwork/clawk/blob/main/docs/commands.md)**.

## Come funziona```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

Alcune scelte deliberate, in breve:

• Il rootfs è una normale immagine OCI. clawk la scarica (senza daemon Docker), appiattisce i layer e scrive direttamente un disco ext4, senza root e senza dispositivi loop. Ogni sandbox dalla stessa immagine è un clone copy-on-write (clonefile APFS / FICLONE), quindi il costo di disco per sandbox è ciò che scrive il guest.
• La rete è filtrata al di sotto del guest. L'intero L3 della VM (gateway, DHCP, DNS, NAT) è uno stack in userspace all'interno del processo daemon. Ogni connessione in uscita e ogni risposta DNS consulta la allow-list lì, dove nemmeno root all'interno del guest può modificarla. Niente iptables sull'host, niente sudo.
• Un solo punto di ingresso. Niente sshd, niente cloud-init: un singolo agente vsock è l'unico percorso di controllo nel guest, e ogni attach è in stile container-exec: un processo nuovo, terminato alla disconnessione.

Il quadro completo (lo stack del guest, entrambi i provider, la rete a livello di frame) è in ARCHITECTURE.md, e le motivazioni dietro ogni decisione in DESIGN.md.

Rispetto a

• Container e devcontainer. Condividono il tuo kernel e vedono il tuo filesystem meno le regole di deny; un singolo bug del kernel o un mount sbagliato può esporre l'host. Le configurazioni devcontainer spesso montano il socket Docker dell'host per costruire immagini, dando al container il controllo del daemon host; clawk invece tiene Docker dentro la VM. E non c'è alcun Dockerfile/devcontainer.json da scrivere: qualsiasi immagine OCI è il rootfs.
• Sandbox a livello di sistema operativo con agenti. Strumenti come sandbox-runtime di Anthropic applicano protezioni a livello di processo sulla tua macchina reale: ottimi per regole leggere, ma un singolo errore di policy espone tutto (chiavi incluse), e installazioni, servizi in background o un hypervisor annidato sono difficili da consentire in sicurezza. clawk sposta l'intero carico di lavoro su una macchina diversa.
• Gestori di VM generici (es. Lima). Lima ti dà una VM Linux; clawk è un workflow sopra una: una VM per progetto con il repo montato, un agente collegato e autenticato, egress allow-listato per impostazione predefinita e denial registrati, conversazioni dell'agente persistite tra le distruzioni, e una modalità ticket che gestisce worktree e PR. (Sotto il cofano entrambi usano Virtualization.framework.)
• Sandbox cloud. Local-first: il tuo codice non lascia mai la macchina, nulla viene fatturato a ore, e il worktree che l'agente modifica è quello nel tuo editor, montato live su macOS (il provider Linux attualmente lo incorpora alla creazione; vedi Roadmap). Le sandbox cloud vanno bene per flotte; clawk è per la macchina sulla tua scrivania.

Modello di sicurezza (e i suoi limiti)

Due confini fanno il lavoro: la VM (il filesystem host è invisibile tranne ciò che monti) e la allow-list in uscita (applicata in userspace sotto il guest, per ogni protocollo che può uscirne). Ciò contro cui clawk non protegge:

• Tutto ciò che monti o permetti è esposto. I worktree sono scrivibili, quindi un agente può committare codice dannoso o fare push su qualsiasi repo raggiungibile dal tuo ssh-agent inoltrato. Rivedi ciò che esce da una sandbox come rivederesti la PR di uno sconosciuto.
• I segreti che inserisci sono visibili. I contenuti di files ( … ) e shares ( … ), le variabili d'ambiente inoltrate e il token Claude sono leggibili dall'agente (e, se una destinazione è allow-listata, inviabili lì). Condividi il minimo.
• Escape dell'hypervisor. clawk si affida all'isolamento di Virtualization.framework/KVM; non aggiunge difese oltre a queste.

Se trovi un modo per violare un confine (escape guest-to-host, bypass del filtro di rete, perdita di credenziali), segnalalo privatamente tramite SECURITY.md.

FAQ

Qual è l'overhead? Il primo avvio da un'immagine paga una costruzione del rootfs una tantum (pull → flatten → ext4). Dopo, i dischi sono cloni copy-on-write e il kernel fa il direct-boot, senza firmware e senza installer. Le VM inattive rilasciano memoria fino a ~1 GiB, si fermano automaticamente dopo 30 minuti di inattività e possono essere salvate su disco così costano solo storage.

Funziona su Mac Intel? Windows? No. macOS richiede Apple silicon (macOS 14+). Su Linux, il provider firecracker funziona ma è sperimentale (vedi docs/commands.md). Nessun supporto Windows.

Devo avere Docker installato? No. clawk scarica immagini OCI e costruisce dischi avviabili da solo. Le immagini Docker sono il formato di input; il motore Docker non è coinvolto. (Eseguire un daemon Docker dentro una sandbox è una funzionalità separata e opzionale; vedi Images per i requisiti hardware e kernel.)

Perché "clawk"? Il marchio è un artiglio; clawkwork è un gioco di parole su Arancia Meccanica. Una VM che carichi, lasci andare e puoi sempre resettare.

Roadmap

Prossimo passo: eseguire più sandbox di quante la tua RAM possa contenerne contemporaneamente.

• Stop di inattività con snapshot. Sospensione su disco manuale fornita come clawk snapshot / clawk resume; poi, anche lo stop di inattività automatico la userà, così i server di sviluppo sopravvivono allo stop e una sandbox sospesa costa solo disco.
• Un tetto alle VM in esecuzione. Invece di rifiutare una nuova VM quando la RAM è impegnata, sospendi su disco la sandbox usata meno di recente e avvia quella nuova.
• Parità Firecracker. Propagazione live del worktree e push di file host su Linux.

Stato

Pre-1.0 e in sviluppo attivo, in rapida evoluzione: aspettati modifiche sostanziali tra le release. La superficie CLI cambia meno e gli interni di più, ma nulla è congelato fino alla 1.0.

Contribuire

Issue e PR sono benvenute. Vedi CONTRIBUTING.md per compilare e testare, ARCHITECTURE.md per come è costruito e DESIGN.md per dove è diretto.

Licenza

Apache License 2.0. clawk include due componenti di terze parti sotto le proprie licenze (gvisor-tap-vsock, Apache-2.0; un writer ext4 di hcsshim, MIT); vedi NOTICE.