clawk

Donnez à un agent de codage sa propre machine Linux jetable, pas la vôtre.

Installation · Démarrage rapide · Pourquoi une VM ? · Comment ça marche · Comparé à · FAQ · Docs

Un agent de codage n'est utile que si vous le laissez réellement faire des choses : installer des paquets, exécuter le code qu'il écrit, démarrer des serveurs, utiliser le réseau. Sur votre propre machine, cela laisse deux mauvaises options. Vous approuvez chaque commande (et surveillez une invite toutes les quelques secondes), ou vous lancez --dangerously-skip-permissions et espérez que rien d'important ne se trouve à un rm -rf ou à un jeton divulgué près.

clawk est une troisième option. cd dans un dépôt, tapez clawk, et Claude Code (ou Codex, ou pi, ou un shell) travaille à l'intérieur d'une VM Linux jetable (votre code monté dedans, root dans l'invité, aucune invite de permission) pendant que vos fichiers, votre trousseau, et le reste de votre machine restent hors de portée. L'agent obtient sa propre machine au lieu de la vôtre.

_{Une commande pour un agent opérationnel ; une tentative d'envoyer des données à un serveur inconnu, bloquée par la liste d'autorisation réseau ; clawk attach reprend la session plus tard.}

La frontière n'est pas une règle dans une invite dont on pourrait convaincre l'agent de sortir. C'est une machine séparée, et les seules ouvertures sont celles que vous avez montées. Depuis un shell à l'intérieur d'un 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.

Pour être honnête sur les limites, la liste d'autorisation bloque les connexions vers des serveurs *inconnus*, pas vers ceux que vous avez autorisés : github.com est pré-autorisé et l'agent ssh transféré peut pousser, donc considérez tout ce que l'agent peut lire comme quelque chose qu'il pourrait publier. Le [modèle de sécurité](#security-model-and-its-limits) détaille cela.

Et si l'agent casse la VM, lancez `clawk destroy && clawk` : une nouvelle VM, le même dépôt, et `--resume` restaure la conversation.

> [!IMPORTANT]
> **Avant la 1.0 et en évolution rapide.** Attendez-vous à des changements cassants entre les versions et à quelques aspérités occasionnelles ; les choses peuvent et vont casser. Veuillez signaler les problèmes ; ces retours façonnent la 1.0.

## Points forts

- **Laissez l'agent faire n'importe quoi.** Il s'exécute dans une VM jetable avec un réseau restreint, donc `rm -rf`, les installations de paquets et le code non fiable ne peuvent pas atteindre votre hôte, vos fichiers ou quoi que ce soit que vous n'avez pas explicitement partagé.
- **Travail en une seule commande.** `cd` dans un dépôt et lancez `clawk`. Pas de Dockerfile, devcontainer ou fichier de configuration. Le premier démarrage construit un rootfs à partir de votre image ; chaque démarrage suivant ne prend que quelques secondes.
- **Cassez-le sans rien perdre.** Détruisez et recréez librement ; votre code et les conversations de l'agent vivent sur l'hôte. Seul le disque de la VM jetable est perdu.
- **Une vraie machine Linux, votre chaîne d'outils.** Toute image OCI est le rootfs : un système d'exploitation complet avec exactement les outils dont votre projet a besoin. Aucun démon Docker requis.
- **Les secrets restent sur votre machine.** Le trafic sortant est sur liste d'autorisation et votre agent ssh est transféré, donc `git push` fonctionne sans que les clés entrent dans la VM.
- **Un bac à sable par projet ou ticket.** Lancez-en plusieurs à la fois ; les tickets multi-dépôts obtiennent un worktree git par dépôt avec des PR coordonnées. Les VM inactives libèrent automatiquement la mémoire et se suspendent sur disque, donc un bac à sable oublié ne coûte (presque) rien.

## Pourquoi une VM ?

clawk est un environnement local polyvalent pour les agents de codage autonomes. La VM est le point central : c'est une machine entière que l'agent peut posséder, pas un processus enveloppé dans une politique sur celle que vous utilisez.

- **Un noyau séparé.** L'invité exécute son propre noyau Linux, donc le système de fichiers de l'hôte n'est pas caché derrière des règles de refus ; il n'a jamais été monté.
- **Un environnement Linux conventionnel.** Noyau standard, userland standard, attentes en forme de `/dev/kvm`, donc les outils se comportent comme le disent leurs docs, sans surprise de filtre d'appels système.
- **Root dans l'invité.** Installez des paquets système, modifiez `/etc`, chargez un module, liez un port privilégié. C'est la machine de l'agent à reconfigurer.
- **Un cycle de vie jetable.** Peu coûteux à casser et rapide à recréer ; une VM détruite est à un `clawk destroy && clawk` près, avec votre dépôt et vos conversations intacts sur l'hôte.
- **Une séparation plus forte de l'hôte.** L'isolation repose sur la frontière de l'hyperviseur plutôt que sur l'obtention d'une politique de bac à sable de processus parfaitement réglée.

Cette combinaison exécute des charges de travail qu'un bac à sable de processus restreint a tendance à vous compliquer :

- installer des paquets et des dépendances natives ;
- exécuter des services en arrière-plan (bases de données, files d'attente, serveurs de développement) ;
- exécuter des builds et des tests non fiables à pleine vitesse ;
- utiliser des outils Linux au niveau système qui attendent une vraie machine ;
- et, avec un noyau invité compatible KVM sur du matériel pris en charge, des flux de travail de développement conteneur et Kubernetes tels que Docker ou Kind s'exécutant *à l'intérieur* du bac à sable. C'est optionnel et limité par le matériel ; voir [Images](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override) pour les exigences exactes.

Rien de tout cela n'est le *produit* ; clawk est destiné au travail d'agent local en général. Docker et Kubernetes ne sont que l'exemple le plus frappant de « a besoin d'une vraie machine, pas d'un processus en bac à sable ».

## Installation

Nécessite macOS 14+ sur Apple silicon. (Linux est pris en charge via firecracker et actuellement expérimental — commencez par **[docs/linux-quickstart.md](https://github.com/clawkwork/clawk/blob/main/docs/linux-quickstart.md)**, qui couvre la configuration, le flux de travail et les lacunes. Ce README est d'abord orienté macOS.)```sh
brew install clawkwork/tap/clawk

Depuis la source (contributeurs, ou si vous n'utilisez pas Homebrew), nécessite Go 1.26+ :```sh git clone https://github.com/clawkwork/clawk && cd clawk make install

De toute façon, il n'y a pas d'outillage hôte supplémentaire : pas de Docker, pas de qemu, pas de sudo. L'hyperviseur est le Virtualization.framework d'Apple, lié dans le binaire, et les binaires de release embarquent l'agent invité précompilé — donc une chaîne d'outils Go n'est nécessaire que si vous compilez depuis les sources, auquel cas vous en avez une. La première exécution détecte tout élément manquant et propose de le corriger.

**Désinstallation :** `clawk destroy` vos sandboxes, `rm -rf ~/.clawk`, puis supprimez le binaire avec `brew uninstall clawk` (ou supprimez-le de `$GOBIN` pour une installation depuis les sources). Rien d'autre n'a été installé : il n'y a pas de jobs launchd ; les démons par sandbox sont des processus ordinaires qui se terminent avec leurs VM.

## Démarrage rapide

Le cas courant, une sandbox pour le répertoire dans lequel vous vous trouvez :```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)

Options communes :```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

Travailler sur un ticket qui s’étend sur plusieurs dépôts ? Une seule commande crée un
bac à sable avec un worktree git par dépôt sur une nouvelle branche, et `clawk pr` ouvre
ensuite des PR liées entre elles pour tout ce qui a changé :```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

Le cycle de vie complet des tickets (statut, branches de suivi après les fusions, rebases) est décrit dans docs/ticket-mode.md.

Astuce : vous utilisez Claude Code ? Exécutez claude setup-token puis clawk auth set-token une seule fois, et chaque sandbox démarre déjà connecté, sans /login et sans conflits de connexion entre les sandbox parallèles. Voir docs/claude-auth.md.

Ce qui survit à quoi

Une seule règle régit la persistance : la VM est jetable ; tout ce qui vous manquerait vit sur l'hôte.

* Deux exceptions : la reprise d'un clawk snapshot restaure le disque et la mémoire exactement tels qu'ils étaient suspendus, et le fournisseur Linux/firecracker conserve son disque jusqu'à destroy. Les outils dont chaque démarrage a besoin appartiennent à l'image (vm ( image … )) ; la configuration par démarrage appartient aux hooks on up.

L'état de l'agent est monté sur l'hôte par sandbox : le répertoire personnel de chaque runner — ~/.claude/ de claude, ~/.codex/ de codex, ~/.pi/ de pi, les deux répertoires XDG d'opencode — se trouve sous ~/.clawk/namespaces/default/state/<name>/ sur l'hôte, donc un sandbox recréé reprend ses anciennes conversations avec --resume. Ce montage est ce qui rend la promesse réelle : le disque de la VM lui-même est re-cloné depuis l'image à chaque démarrage, donc tout ce qu'un runner écrit en dehors de ces répertoires disparaît au prochain clawk up.

Autonomie complète par défaut (et l'option de retrait --safe)

Les runners se lancent dans leurs modes « sandboxés en externe » : claude reçoit --dangerously-skip-permissions, codex reçoit --dangerously-bypass-approvals-and-sandbox, pi reçoit --approve (il n'a pas d'invites d'approbation à contourner — il n'est livré avec aucun sandbox — mais il verrouille bien les paramètres et extensions .pi/ locaux au projet derrière une invite de confiance), et opencode reçoit --auto. Sur votre propre machine, ces drapeaux seraient imprudents ; ici, ils sont le but : la frontière de la VM et la liste d'autorisation réseau fournissent le confinement, donc l'agent travaille à pleine vitesse sans invites par action. L'agent ne peut affecter que ce que vous avez monté et autorisé, rien de plus (voir SECURITY.md).

Vous préférez quand même les invites de confirmation ? Ajoutez --safe à toute connexion (clawk --safe, clawk run claude --safe) et le runner démarre sans ses drapeaux de contournement pour cette session.

Réseau

Le trafic sortant est refusé par défaut ; chaque sandbox a sa propre liste d'autorisation. Le DNS résout tout ; les TCP, UDP (y compris QUIC) et les échos ICMP vers des hôtes non listés sont refusés. Les registres courants (npm, PyPI, crates.io, GitHub, Anthropic, …) sont pré-autorisés, et le filtre est sensible au DNS, donc autoriser example.com continue de fonctionner à mesure que ses IP changent.```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

Les refus sont enregistrés par le *nom d'hôte que l'invité a résolu*, donc `clawk network
denials` se lit comme un journal de ce que l'agent a tenté d'atteindre. Les politiques
nommées réutilisables (y compris l'abonnement à des listes noires externes comme oisd) et la
chaîne `use` qui les superpose sont dans
**[docs/networking.md](https://github.com/clawkwork/clawk/blob/main/docs/networking.md)**.

## Configuration : `clawk.mod`

Aucun fichier de configuration n'est requis ; les valeurs par défaut sont raisonnables. Lorsqu'un projet en a besoin
de plus, un fichier `clawk.mod` le décrit, dans une syntaxe de style 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."
    )
)

Le bloc est un modèle : il est figé lors de la création du sandbox, de sorte qu'un sandbox en cours d'exécution ne change jamais de manière inattendue. La référence complète (partages, fichiers secrets, compétences, amorçage de la mémoire de l'agent, racines de workspace multi-dépôts) se trouve dans docs/configuration.md ; les serveurs MCP et la manière dont leurs identifiants restent hors du disque sont dans docs/mcp.md ; l'intégration d'une carte USB-série depuis votre Mac dans le sandbox pour le travail sur microcontrôleurs est dans docs/serial.md ; les images et les noyaux invités personnalisés (y compris le noyau compatible KVM utilisé pour la virtualisation imbriquée) sont dans docs/images.md.

Cycle de vie```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` est l'hibernation pour les sandboxes : la mémoire de l'invité est sauvegardée
à côté de son disque et le prochain démarrage restaure l'invité exactement là où il en était.
Les processus en arrière-plan et les serveurs de développement continuent comme si de rien n'était, et
`clawk attach` vous replace devant l'agent. La surface complète des commandes,
la répartition des exécuteurs, et la machinerie de gestion de l'inactivité (ballooning, contrôle
d'admission, arrêt automatique) sont dans **[docs/commands.md](https://github.com/clawkwork/clawk/blob/main/docs/commands.md)**.

## Comment ça fonctionne```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

Quelques choix délibérés, en bref :

• Le rootfs est une image OCI ordinaire. clawk la récupère (sans démon Docker), aplatit les couches et écrit directement un disque ext4, sans root ni périphériques loop. Chaque sandbox issu de la même image est un clone copy-on-write (clonefile APFS / FICLONE), donc le coût disque par sandbox correspond à ce que l'invité écrit.
• Le réseau est filtré sous l'invité. Tout le L3 de la VM (passerelle, DHCP, DNS, NAT) est une pile en espace utilisateur dans le processus du démon. Chaque connexion sortante et chaque réponse DNS consultent la liste d'autorisation là-bas, où même root dans l'invité ne peut pas la modifier. Pas d'iptables hôte, pas de sudo.
• Une seule voie d'entrée. Pas de sshd, pas de cloud-init : un unique agent vsock est le seul chemin de contrôle vers l'invité, et chaque attachement est de style container-exec : un processus neuf, démantelé à la déconnexion.

Le tableau complet (la pile invitée, les deux fournisseurs, le réseau au niveau trame) se trouve dans ARCHITECTURE.md, et le raisonnement derrière chaque décision dans DESIGN.md.

Comparé à

• Conteneurs et devcontainers. Ils partagent votre noyau et voient votre système de fichiers moins les règles de refus ; un seul bug de noyau ou un montage erroné peut exposer l'hôte. Les configurations devcontainer montent souvent le socket Docker de l'hôte en bind-mount pour construire des images, donnant au conteneur le contrôle du démon hôte ; clawk garde Docker à l'intérieur de la VM à la place. Et il n'y a pas de Dockerfile/devcontainer.json à écrire : toute image OCI est le rootfs.
• Sandboxes d'agents au niveau OS. Des outils comme sandbox-runtime d'Anthropic appliquent des garde-fous au niveau processus sur votre vraie machine : parfaits pour des règles légères, mais une seule erreur de politique expose tout (trousseau inclus), et les installations, services d'arrière-plan ou un hyperviseur imbriqué sont difficiles à autoriser en toute sécurité. clawk déplace toute la charge de travail sur une autre machine.
• Gestionnaires de VM à usage général (ex. Lima). Lima vous donne une VM Linux ; clawk est un workflow par-dessus : une VM par projet avec le dépôt monté, un agent attaché et authentifié, l'egress autorisée par liste par défaut et les refus journalisés, les conversations d'agent persistées entre les destructions, et un mode ticket qui gère les worktrees et les PR. (Sous le capot, les deux utilisent Virtualization.framework.)
• Sandboxes cloud. Local d'abord : votre code ne quitte jamais la machine, rien n'est facturé à l'heure, et le worktree que l'agent édite est celui de votre éditeur, monté en direct sur macOS (le fournisseur Linux l'intègre actuellement à la création ; voir Roadmap). Les sandboxes cloud conviennent aux flottes ; clawk est pour la machine sur votre bureau.

Modèle de sécurité (et ses limites)

Deux frontières font le travail : la VM (le système de fichiers hôte est invisible sauf ce que vous montez) et la liste d'autorisation sortante (appliquée en espace utilisateur sous l'invité, pour chaque protocole qui peut la quitter). Ce contre quoi clawk ne protège pas :

• Tout ce que vous montez ou autorisez est exposé. Les worktrees sont inscriptibles, donc un agent peut committer du mauvais code ou pousser vers tout dépôt que votre ssh-agent transféré peut atteindre. Relisez ce qui sort d'une sandbox comme vous reliriez la PR d'un inconnu.
• Les secrets que vous injectez sont visibles. Les contenus de files ( … ) et shares ( … ), les variables d'environnement transférées et le jeton Claude sont à la portée de l'agent (et, si une destination est autorisée, à envoyer là-bas). Partagez le minimum.
• Évasions d'hyperviseur. clawk repose sur l'isolation Virtualization.framework/KVM ; il n'ajoute pas de défenses au-delà.

Si vous trouvez un moyen de franchir une frontière (évasion invité-vers-hôte, contournement du filtre réseau, fuite d'identifiants), veuillez le signaler en privé via SECURITY.md.

FAQ

Quel est le surcoût ? Le premier démarrage depuis une image paie une construction rootfs unique (pull → aplatissement → ext4). Ensuite, les disques sont des clones copy-on-write et le noyau démarre directement, sans firmware ni installeur. Les VM inactives libèrent de la mémoire jusqu'à ~1 Gio, s'arrêtent automatiquement après 30 minutes d'inactivité et peuvent être instantanées sur disque pour ne coûter que du stockage.

Ça fonctionne sur les Mac Intel ? Windows ? Non. macOS nécessite Apple silicon (macOS 14+). Sur Linux, le fournisseur firecracker fonctionne mais est expérimental (voir docs/commands.md). Pas de support Windows.

Ai-je besoin d'installer Docker ? Non. clawk récupère les images OCI et construit lui-même des disques amorçables. Les images Docker sont le format d'entrée ; le moteur Docker n'est pas impliqué. (Exécuter un démon Docker à l'intérieur d'une sandbox est une fonctionnalité distincte et optionnelle ; voir Images pour les exigences matérielles et de noyau.)

Pourquoi « clawk » ? La marque est une griffe ; clawkwork est un jeu de mots sur Orange mécanique. Une VM que vous remontez, lâchez, et pouvez toujours réinitialiser.

Roadmap

À venir : exécuter plus de sandboxes que votre RAM ne peut en contenir à la fois.

• Arrêts d'inactivité avec instantané. Suspension manuelle sur disque livrée comme clawk snapshot / clawk resume ; ensuite, l'arrêt d'inactivité automatique l'utilisera aussi, pour que les serveurs de dev survivent à l'arrêt et qu'une sandbox suspendue ne coûte que du disque.
• Un plafond sur les VM en cours. Au lieu de refuser une nouvelle VM quand la RAM est engagée, suspendre la sandbox la moins récemment utilisée sur disque et démarrer la nouvelle.
• Parité firecracker. Propagation de worktree en direct et envoi de fichiers hôte sur Linux.

Statut

Pré-1.0 et en développement actif, évoluant rapidement : attendez-vous à des changements cassants entre les versions. La surface CLI change le moins et les internes le plus, mais rien n'est figé avant la 1.0.

Contribuer

Les issues et les PR sont les bienvenues. Voir CONTRIBUTING.md pour construire et tester, ARCHITECTURE.md pour savoir comment c'est construit, et DESIGN.md pour savoir où ça va.

Licence

Licence Apache 2.0. clawk fournit deux composants tiers sous leurs propres licences (gvisor-tap-vsock, Apache-2.0 ; un écrivain ext4 hcsshim, MIT) ; voir NOTICE.