
Gib Coding-Agenten eine Wegwerf-Linux-VM, nicht deinen Laptop
Gib einem Coding-Agenten seine eigene Wegwerf-Linux-Maschine, nicht deine.
Installation · Schnellstart · Warum eine VM? · So funktioniert es · Im Vergleich zu · FAQ · Doku
Ein Coding-Agent ist nur dann nützlich, wenn du ihn tatsächlich Dinge tun
lässt: Pakete installieren, den von ihm geschriebenen Code ausführen, Server
starten, das Netzwerk nutzen. Auf deinem eigenen Rechner bleiben dir dabei zwei
schlechte Optionen. Du genehmigst jeden Befehl (und beaufsichtigst alle paar
Sekunden eine Eingabeaufforderung), oder du führst --dangerously-skip-permissions
aus und hoffst, dass nichts Wichtiges nur ein rm -rf oder ein geleakter Token
entfernt ist.
clawk ist eine dritte Option. cd in ein Repo, tippe clawk, und Claude Code
(oder Codex, oder pi, oder eine Shell) arbeitet in einer Wegwerf-Linux-VM (dein
Code eingehängt, Root im Gast, keine Berechtigungsabfragen), während deine
Dateien, dein Schlüsselbund und der Rest deines Rechners außer Reichweite
bleiben. Der Agent bekommt seine eigene Maschine statt deiner.
Ein Befehl zu einem funktionierenden Agenten; ein Versuch, Daten an
einen unbekannten Server zu senden, blockiert durch die Netzwerk-Allowlist;
clawk attach setzt die Sitzung später fort.
Die Grenze ist keine Regel in einem Prompt, aus der der Agent herausgeredet werden könnte. Es ist eine separate Maschine, und die einzigen Öffnungen sind diejenigen, die du eingehängt hast. Aus einer Shell innerhalb einer 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.
Um ehrlich über die Grenzen zu sein: Die Allow-List blockiert Verbindungen zu *unbekannten*
Servern, nicht zu solchen, die du erlaubt hast: github.com ist vorab erlaubt und der
weitergereichte ssh-agent kann pushen. Behandle also alles, was der Agent lesen kann, als etwas,
das er veröffentlichen könnte. Das
[Sicherheitsmodell](#sicherheitsmodell-und-seine-grenzen) führt das im Detail aus.
Und falls der Agent die VM zerstört, führe `clawk destroy && clawk` aus: eine frische VM, dasselbe
Repo, und `--resume` stellt die Konversation wieder her.
> [!IMPORTANT]
> **Vor 1.0 und schnelle Entwicklung.** Erwarte bahnbrechende Änderungen zwischen Releases und
> gelegentlich raue Kanten; Dinge können und werden kaputtgehen. Bitte melde Issues;
> dieses Feedback formt 1.0.
## Highlights
- **Lass den Agenten alles tun.** Er läuft in einer Wegwerf-VM mit eingeschränktem
Netzwerk, sodass `rm -rf`, Paketinstallationen und nicht vertrauenswürdiger Code deinen
Host, deine Dateien oder alles, was du nicht explizit geteilt hast, nicht erreichen können.
- **Arbeiten mit einem Befehl.** `cd` in ein Repo und `clawk` ausführen. Keine
Dockerfile, kein Devcontainer, keine Setup-Datei. Der erste Start baut ein Rootfs aus
deinem Image; jeder weitere Start dauert Sekunden.
- **Kaputtmachen, ohne etwas zu verlieren.** Frei zerstören und neu erstellen; dein
Code und die Konversationen des Agenten leben auf dem Host. Nur die Wegwerf-VM-Festplatte
geht verloren.
- **Eine echte Linux-Box, deine Toolchain.** Jedes OCI-Image ist das Rootfs: ein vollständiges
Betriebssystem mit genau den Tools, die dein Projekt braucht. Kein Docker-Daemon erforderlich.
- **Geheimnisse bleiben auf deiner Maschine.** Ausgehender Datenverkehr ist auf eine Allow-List
beschränkt und dein ssh-agent wird weitergereicht, sodass `git push` funktioniert, ohne dass
Schlüssel in die VM gelangen.
- **Eine Sandbox pro Projekt oder Ticket.** Mehrere gleichzeitig ausführen; Multi-Repo-
Tickets erhalten ein Git-Worktree pro Repo mit koordinierten PRs. Leerlaufende VMs
geben automatisch Speicher frei und suspendieren auf die Festplatte, sodass eine vergessene
Sandbox (fast) nichts kostet.
## Warum eine VM?
clawk ist eine universelle lokale Umgebung für autonome Coding-Agenten.
Die VM ist der Punkt: Sie ist eine ganze Maschine, die der Agent besitzen kann, kein Prozess,
der in Richtlinien auf der Maschine eingewickelt ist, die du gerade verwendest.
- **Ein separater Kernel.** Der Gast läuft mit seinem eigenen Linux-Kernel, sodass das Host-
Dateisystem nicht hinter Deny-Regeln versteckt ist; es wurde nie eingehängt.
- **Eine konventionelle Linux-Umgebung.** Standard-Kernel, Standard-Userland,
`/dev/kvm`-artige Erwartungen, sodass Tools sich so verhalten, wie ihre Dokumentation es sagt,
ohne eine Syscall-Filter-Überraschung.
- **Root im Gast.** Systempakete installieren, `/etc` bearbeiten, ein Modul laden,
einen privilegierten Port binden. Es ist die Box des Agenten, die er neu konfigurieren kann.
- **Ein Wegwerf-Lebenszyklus.** Billig zu zerstören und schnell neu zu erstellen; eine zerstörte
VM ist nur ein `clawk destroy && clawk` entfernt, wobei dein Repo und deine Konversationen
auf dem Host unberührt bleiben.
- **Stärkere Trennung vom Host.** Die Isolierung beruht auf der Hypervisor-Grenze
und nicht darauf, eine Prozess-Sandbox-Richtlinie exakt richtig hinzubekommen.
Diese Kombination führt Workloads aus, gegen die eine eingeschränkte Prozess-Sandbox oft
ankämpft:
- Installieren von Paketen und nativen Abhängigkeiten;
- Ausführen von Hintergrunddiensten (Datenbanken, Warteschlangen, Dev-Server);
- Ausführen nicht vertrauenswürdiger Builds und Tests mit voller Geschwindigkeit;
- Verwenden von Linux-System-Tools, die eine echte Maschine erwarten;
- und, mit einem KVM-fähigen Gast-Kernel auf unterstützter Hardware, Container- und
Kubernetes-Dev-Workflows wie Docker oder Kind, die *innerhalb* der
Sandbox laufen. Dies ist opt-in und hardwareabhängig; siehe
[Images](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override) für die genauen Anforderungen.
Nichts davon ist das *Produkt*; clawk ist allgemein für lokale Agentenarbeit gedacht.
Docker und Kubernetes sind nur das schärfste Beispiel für „braucht eine echte Maschine,
keinen sandboxed Prozess."
## Installation
Erfordert macOS 14+ auf Apple Silicon. (Linux wird über firecracker unterstützt und ist
derzeit experimentell — beginne mit
**[docs/linux-quickstart.md](https://github.com/clawkwork/clawk/blob/main/docs/linux-quickstart.md)**, das Setup,
den Workflow und die Lücken abdeckt. Dieses README ist macOS-zuerst.)```sh
brew install clawkwork/tap/clawk
Aus der Quelle (Mitwirkende, oder falls du Homebrew nicht verwendest), benötigt Go 1.26+:```sh git clone https://github.com/clawkwork/clawk && cd clawk make install
So oder so gibt es keine zusätzliche Host-Tooling: kein Docker, kein qemu, kein sudo. Der
Hypervisor ist Apples Virtualization.framework, direkt in die Binärdatei eingebunden, und die
Release-Binärdateien enthalten den In-Guest-Agent bereits vorgebaut — eine Go-Toolchain wird also
nur benötigt, wenn du aus dem Quellcode baust, und in dem Fall hast du eine. Der erste Lauf prüft
auf fehlende Komponenten und bietet an, sie zu beheben.
**Deinstallation:** `clawk destroy` deine Sandboxes, `rm -rf ~/.clawk`, dann entferne
die Binärdatei mit `brew uninstall clawk` (oder lösche sie aus `$GOBIN` bei einer
Quellinstallation). Sonst wurde nichts installiert: Es gibt keine launchd-Jobs; die
Pro-Sandbox-Daemons sind gewöhnliche Prozesse, die mit ihren VMs beendet werden.
## Schnellstart
Der alltägliche Fall, eine Sandbox für das Verzeichnis, in dem du dich befindest:```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)
Gemeinsame Optionen:```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
Arbeitest du an einem Ticket, das sich über mehrere Repositories erstreckt? Ein einziger Befehl erstellt eine
Sandbox mit einem Git-Worktree pro Repository auf einem frischen Branch, und `clawk pr` öffnet später
cross-verlinkte PRs für alles, was sich geändert hat:```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
Der vollständige Ticket-Lebenszyklus (Status, Folge-Branches nach Merges, Rebases) ist in docs/ticket-mode.md dokumentiert.
Tipp: Nutzt du Claude Code? Führe
claude setup-tokenund dannclawk auth set-tokeneinmal aus, und jede Sandbox startet bereits angemeldet, ohne/loginund ohne Login-Konflikte zwischen parallelen Sandboxes. Siehe docs/claude-auth.md.
Eine Regel bestimmt die Persistenz: die VM ist wegwerfbar; alles, was du vermissen würdest, lebt auf dem Host.
* Zwei Ausnahmen: Das Fortsetzen eines clawk snapshot stellt die Festplatte und
den Speicher exakt so wieder her, wie sie ausgesetzt wurden, und der Linux/Firecracker-Provider
behält seine Festplatte bis zum Destroy. Tools, die jeder Boot benötigt, gehören in das Image
(vm ( image … )); Setup pro Boot gehört in on up-Hooks.
Der Agent-Zustand ist pro Sandbox auf dem Host gemountet: das Home-Verzeichnis jedes Runners —
claudes ~/.claude/, codex' ~/.codex/, pis ~/.pi/, opencodes zwei XDG-Verzeichnisse —
liegen unter
~/.clawk/namespaces/default/state/<name>/ auf dem Host, sodass eine neu erstellte
Sandbox ihre alten Konversationen mit --resume aufnimmt. Dieser Mount macht das
Versprechen real: Die VM-Festplatte selbst wird bei jedem Boot neu aus dem Image geklont,
also ist alles, was ein Runner außerhalb dieser Verzeichnisse schreibt, beim nächsten
clawk up verschwunden.
--safe-Opt-out)Runner starten in ihren „extern gesandboxten" Modi: claude erhält
--dangerously-skip-permissions, codex erhält
--dangerously-bypass-approvals-and-sandbox, pi erhält --approve (es hat keine
Genehmigungsaufforderungen zu umgehen — es bringt gar keine Sandbox mit —, aber es sperrt
projektlokale .pi/-Einstellungen und Erweiterungen hinter einer Vertrauensaufforderung), und
opencode erhält --auto. Auf deinem eigenen Rechner wären diese Flags
rücksichtslos; hier sind sie der Punkt: Die VM-Grenze und die Netzwerk-
Allow-Liste sorgen für die Eindämmung, sodass der Agent mit voller Geschwindigkeit ohne
Aufforderungen pro Aktion arbeitet. Der Agent kann nur das beeinflussen, was du gemountet und
auf die Allow-Liste gesetzt hast, nichts weiter (siehe SECURITY.md).
Bevorzugst du trotzdem die Bestätigungsaufforderungen? Füge --safe zu jedem Attach hinzu
(clawk --safe, clawk run claude --safe) und der Runner startet für diese Sitzung ohne
seine Bypass-Flags.
Ausgehender Datenverkehr ist standardmäßig verweigert; jede Sandbox hat ihre eigene Allow-Liste.
DNS löst alles auf; TCP, UDP (einschließlich QUIC) und ICMP-Echo an nicht gelistete
Hosts werden abgelehnt. Gängige Registries (npm, PyPI, crates.io, GitHub,
Anthropic, …) sind vorab erlaubt, und der Filter ist DNS-bewusst, sodass das Erlauben
von example.com weiterhin funktioniert, während sich dessen IPs drehen.```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 werden anhand des *Hostnamens, den der Gast aufgelöst hat*, protokolliert, sodass `clawk network denials` als Protokoll darüber gelesen werden kann, was der Agent zu erreichen versuchte. Wiederverwendbare benannte Richtlinien (einschließlich des Abonnierens externer Blocklisten wie oisd) und die `use`-Kette, die sie schichtet, finden sich in
**[docs/networking.md](https://github.com/clawkwork/clawk/blob/main/docs/networking.md)**.
## Konfiguration: `clawk.mod`
Es ist keine Konfigurationsdatei erforderlich; die Standardwerte sind sinnvoll. Wenn ein Projekt mehr benötigt, beschreibt eine `clawk.mod`-Datei dies in einer go.mod-ähnlichen 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."
)
)
Der Block ist eine Vorlage: Er wird beim Erstellen der Sandbox als Schnappschuss gespeichert, sodass eine laufende Sandbox sich nie unerwartet ändert. Die vollständige Referenz (Freigaben, geheime Dateien, Skills, Seeding des Agentenspeichers, Workspace-Roots mit mehreren Repos) finden Sie in docs/configuration.md; MCP-Server und wie deren Anmeldedaten nicht auf der Festplatte verbleiben, finden Sie in docs/mcp.md; das Einbinden einer USB-Serial-Platine von Ihrem Mac in die Sandbox für Mikrocontroller-Arbeiten finden Sie in docs/serial.md; Bilder und benutzerdefinierte Gast-Kernel (einschließlich des für verschachtelte Virtualisierung verwendeten KVM-fähigen Kernels) finden Sie in docs/images.md.
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` ist der Ruhezustand für Sandboxes: Der Speicher des Gasts wird
neben seiner Festplatte gespeichert und der nächste Start stellt den Gast exakt dort wieder her, wo er war.
Hintergrundprozesse und Dev-Server laufen weiter, als wäre nichts passiert, und
`clawk attach` bringt dich zurück vor den Agenten. Die vollständige Befehlsfläche,
die Runner-Dispatch- und die Leerlauf-Verwaltungsmechanik (Ballooning, Admission
Control, Auto-Stop) findest du in **[docs/commands.md](https://github.com/clawkwork/clawk/blob/main/docs/commands.md)**.
## So funktioniert es```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
Einige bewusste Entscheidungen, kurz zusammengefasst:
clonefile / FICLONE), sodass die Festplattenkosten pro Sandbox dem entsprechen, was der Gast schreibt.Das vollständige Bild (der Gast-Stack, beide Provider, das Frame-Level-Netzwerk) findet sich in ARCHITECTURE.md, und die Begründung hinter jeder Entscheidung in DESIGN.md.
Dockerfile/devcontainer.json zu schreiben: Jedes OCI-Image ist das Rootfs.Zwei Grenzen leisten die Arbeit: die VM (das Host-Dateisystem ist unsichtbar, außer was Sie mounten) und die ausgehende Allow-List (durchgesetzt im Userspace unterhalb des Gasts, für jedes Protokoll, das sie verlassen kann). Wovor clawk nicht schützt:
files ( … ) und shares ( … ), weitergeleitete Env-Variablen und das Claude-Token kann der Agent lesen (und, wenn ein Ziel auf der Allow-List steht, dorthin senden). Teilen Sie das Minimum.Wenn Sie einen Weg finden, eine Grenze zu durchbrechen (Gast-zu-Host-Escape, Netzwerkfilter-Umgehung, Credential-Leak), melden Sie es bitte privat über SECURITY.md.
Wie hoch ist der Overhead? Der erste Boot aus einem Image zahlt einen einmaligen Rootfs-Build (Pull → Flatten → ext4). Danach sind die Festplatten Copy-on-Write-Klone und der Kernel bootet direkt, ohne Firmware und ohne Installer. Leerlaufende VMs geben Speicher bis auf ~1 GiB frei, stoppen automatisch nach 30 Leerlaufminuten und können auf die Festplatte gesnapshottet werden, sodass sie nur Speicher kosten.
Funktioniert es auf Intel-Macs? Windows? Nein. macOS benötigt Apple Silicon (macOS 14+). Auf Linux funktioniert der Firecracker-Provider, ist aber experimentell (siehe docs/commands.md). Keine Windows-Unterstützung.
Muss ich Docker installiert haben? Nein. clawk zieht OCI-Images und baut bootfähige Festplatten selbst. Docker-Images sind das Eingabeformat; die Docker-Engine ist nicht beteiligt. (Das Ausführen eines Docker-Daemons innerhalb einer Sandbox ist ein separates, optionales Feature; siehe Images für die Hardware- und Kernel-Anforderungen.)
Warum „clawk"? Das Zeichen ist eine Klaue; clawkwork ist ein Wortspiel auf A Clockwork Orange. Eine VM, die Sie aufziehen, loslassen und immer zurücksetzen können.
Als Nächstes: Mehr Sandboxes ausführen, als Ihr RAM gleichzeitig halten kann.
clawk snapshot / clawk resume ausgeliefert; als Nächstes nutzt auch der automatische Leerlauf-Stopp es, sodass Dev-Server den Stopp überleben und eine suspendierte Sandbox nur Festplatte kostet.Vor 1.0 und in aktiver Entwicklung, die sich schnell weiterentwickelt: Erwarten Sie bahnbrechende Änderungen zwischen Releases. Die CLI-Oberfläche ändert sich am wenigsten und die Interna am meisten, aber nichts ist bis 1.0 eingefroren.
Issues und PRs sind willkommen. Siehe CONTRIBUTING.md zum Bauen und Testen, ARCHITECTURE.md für den Aufbau und DESIGN.md für die Richtung.
Apache License 2.0. clawk bündelt zwei Drittanbieter-Komponenten unter ihren eigenen Lizenzen (gvisor-tap-vsock, Apache-2.0; ein hcsshim-ext4-Writer, MIT); siehe NOTICE.
clawk down |
|---|
clawk destroy |
|---|
| Dein Repo (gemounteter Worktree; Commits, Branches) | ✅ | ✅ |
| Agent-Zustand (Claude/Codex/pi/opencode-Konversationen, Speicher) | ✅ | ✅ |
Die VM-Festplatte (apt-Installationen, Caches, $HOME) | ❌ (bei jedem Boot frisch neu aufgebaut*) | ❌ (das ist der Sinn) |