clawkwork/clawkDale a los agentes de codificación una VM Linux desechable, no tu portátil.
<div align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7237/193b3f67135a6e0f90c36ec914e8c5fd73a4d6181ea56b6ba75e042e6335dc72.png" alt="clawk" width="400">
*Dale a un agente de programación su propia máquina Linux desechable, no la tuya.*
[](https://github.com/clawkwork/clawk/actions/workflows/ci.yml)
[](LICENSE)
[](go.mod)
-lightgrey)
**[Instalación](#install)** · **[Inicio rápido](#quickstart)** ·
**[¿Por qué una VM?](#why-a-vm)** · **[Cómo funciona](#how-it-works)** ·
**[Comparado con](#compared-to)** · **[Preguntas frecuentes](#faq)** · **[Documentación](https://github.com/clawkwork/clawk/blob/main/docs)**
</div>
Un agente de programación solo es útil cuando le dejas realmente *hacer* cosas: instalar
paquetes, ejecutar el código que escribe, iniciar servidores, usar la red. En tu propia
máquina eso deja dos malas opciones. Apruebas cada comando (y atiendes un
aviso cada pocos segundos), o ejecutas `--dangerously-skip-permissions` y esperas
que nada importante esté a un `rm -rf` o a un token filtrado de distancia.
clawk es una tercera opción. Haz `cd` a un repositorio, escribe `clawk`, y Claude Code (o
Codex, o pi, o un shell) estará trabajando dentro de una VM Linux desechable (tu código montado
dentro, root en el invitado, sin avisos de permisos) mientras tus archivos, tu llavero
y el resto de tu máquina quedan fuera de alcance. **El agente obtiene su propia
máquina en lugar de la tuya.**
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7237/56b97e90b5af190abc2e1de5cc7b8ad4e835a05dd6e7a1e2f3416d78021a6a8b.gif" alt="demostración de clawk: clawk arranca una VM y adjunta claude; un intento bloqueado de enviar datos a un servidor desconocido aparece en las denegaciones de red de clawk; clawk attach reanuda el sandbox más tarde" width="760">
<br>
<sub><i>Un comando para tener un agente funcional; un intento de enviar datos a un
servidor desconocido, bloqueado por la lista de permitidos de red; <code>clawk attach</code>
reanuda la sesión más tarde.</i></sub>
</p>
El límite no es una regla en un prompt de la que se pueda convencer al agente. Es
una máquina separada, y las únicas aperturas son las que tú montaste. Desde un
shell dentro de 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.
```
Para ser honestos sobre los límites, la lista de permitidos bloquea las conexiones a servidores *desconocidos*, no a los que has permitido: github.com está pre-permitido y el ssh-agent reenviado puede hacer push, así que trata cualquier cosa que el agente pueda leer como algo que podría publicar. El [modelo de seguridad](#security-model-and-its-limits) lo detalla.
Y si el agente destroza la VM, ejecuta `clawk destroy && clawk`: una VM nueva, el mismo repositorio, y `--resume` restaura la conversación.
> [!IMPORTANT]
> **Pre-1.0 y avanzando rápido.** Espera cambios que rompan la compatibilidad entre versiones y algún que otro borde áspero; las cosas pueden y van a romperse. Por favor, abre issues; ese feedback está dando forma a la 1.0.
## Aspectos destacados
- **Deja que el agente haga cualquier cosa.** Se ejecuta en una VM desechable con una red restringida, así que `rm -rf`, las instalaciones de paquetes y el código no confiable no pueden alcanzar tu host, tus archivos ni nada que no hayas compartido explícitamente.
- **Trabajar con un solo comando.** Haz `cd` a un repositorio y ejecuta `clawk`. Sin Dockerfile, devcontainer ni archivo de configuración. El primer arranque construye un rootfs a partir de tu imagen; cada arranque posterior tarda segundos.
- **Rómpelo sin perder nada.** Destruye y recrea libremente; tu código y las conversaciones del agente viven en el host. Solo se pierde el disco desechable de la VM.
- **Una caja Linux real, tu toolchain.** Cualquier imagen OCI es el rootfs: un SO completo con exactamente las herramientas que tu proyecto necesita. No se requiere demonio de Docker.
- **Los secretos se quedan en tu máquina.** El tráfico saliente está en la lista de permitidos y tu ssh-agent se reenvía, así que `git push` funciona sin que las claves entren en la VM.
- **Un sandbox por proyecto o ticket.** Ejecuta varios a la vez; los tickets multi-repositorio obtienen un git worktree por repositorio con PRs coordinados. Las VM inactivas liberan memoria automáticamente y se suspenden a disco, así que un sandbox olvidado cuesta (casi) nada.
## ¿Por qué una VM?
clawk es un entorno local de propósito general para agentes de codificación autónomos. La VM es el punto: es una máquina completa que el agente puede poseer, no un proceso envuelto en políticas sobre la que estás usando.
- **Un kernel separado.** El invitado ejecuta su propio kernel Linux, así que el sistema de archivos del host no está oculto tras reglas de denegación; nunca estuvo montado.
- **Un entorno Linux convencional.** Kernel estándar, userland estándar, expectativas con forma de `/dev/kvm`, así que las herramientas se comportan como dicen sus docs, sin sorpresas de filtrado de syscalls.
- **Root en el invitado.** Instala paquetes del sistema, edita `/etc`, carga un módulo, enlaza un puerto privilegiado. Es la caja del agente para reconfigurar.
- **Un ciclo de vida desechable.** Barato de romper y rápido de recrear; una VM destrozada está a un `clawk destroy && clawk` de distancia, con tu repositorio y conversaciones intactos en el host.
- **Mayor separación del host.** El aislamiento descansa en la frontera del hipervisor en lugar de acertar exactamente con una política de sandbox de procesos.
Esa combinación ejecuta cargas de trabajo con las que un sandbox de procesos restringido tiende a pelearse contigo:
- instalar paquetes y dependencias nativas;
- ejecutar servicios en segundo plano (bases de datos, colas, servidores de desarrollo);
- ejecutar builds y tests no confiables a plena velocidad;
- usar herramientas Linux a nivel de sistema que esperan una máquina real;
- y, con un kernel invitado habilitado para KVM en hardware compatible, flujos de trabajo de desarrollo de contenedores y Kubernetes como Docker o Kind ejecutándose *dentro* del sandbox. Esto es opcional y está condicionado al hardware; consulta [Images](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override) para los requisitos exactos.
Nada de esto es el *producto*; clawk es para trabajo local con agentes en general. Docker y Kubernetes son solo el ejemplo más claro de "necesita una máquina real, no un proceso en sandbox."
## Instalación
Requiere macOS 14+ en Apple silicon. (Linux es compatible vía firecracker y actualmente es experimental — empieza con **[docs/linux-quickstart.md](https://github.com/clawkwork/clawk/blob/main/docs/linux-quickstart.md)**, que cubre la configuración, el flujo de trabajo y las carencias. Este README está orientado primero a macOS.)
```sh
brew install clawkwork/tap/clawk
```
**Desde el código fuente** (colaboradores, o si no usas Homebrew), requiere Go 1.26+:
```sh
git clone https://github.com/clawkwork/clawk && cd clawk
make install
```
De cualquier manera no hay herramientas adicionales en el host: ni Docker, ni qemu, ni sudo. El hipervisor es Virtualization.framework de Apple, enlazado dentro del binario, y los binarios de la release llevan el agente invitado precompilado — así que solo se necesita una cadena de herramientas de Go si compilas desde el código fuente, en cuyo caso ya la tienes. La primera ejecución sondea cualquier cosa que falte y ofrece solucionarlo.
**Desinstalación:** `clawk destroy` tus sandboxes, `rm -rf ~/.clawk`, luego elimina el binario con `brew uninstall clawk` (o bórralo de `$GOBIN` para una instalación desde el código fuente). No se instaló nada más: no hay trabajos de launchd; los daemons por sandbox son procesos ordinarios que terminan con sus VMs.
## Inicio rápido
El caso cotidiano, un sandbox para el directorio en el que estás:
```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)
```
Opciones comunes:
```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
```
¿Trabajando en un ticket que abarca varios repositorios? Un solo comando crea un
sandbox con un git worktree por repositorio en una rama nueva, y `clawk pr` posteriormente
abre PRs con enlaces cruzados para todo lo que haya cambiado:
```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
```
El ciclo de vida completo del ticket (estado, ramas de seguimiento tras fusiones, rebases) está en **[docs/ticket-mode.md](https://github.com/clawkwork/clawk/blob/main/docs/ticket-mode.md)**.
> **Consejo:** ¿usas Claude Code? Ejecuta `claude setup-token` y luego
> `clawk auth set-token` una vez, y cada sandbox se inicia ya con la sesión iniciada,
> sin `/login` y sin conflictos de inicio de sesión entre sandboxes paralelos. Consulta
> **[docs/claude-auth.md](https://github.com/clawkwork/clawk/blob/main/docs/claude-auth.md)**.
## Qué sobrevive a qué
Una regla rige la persistencia: *la VM es desechable; todo lo que echarías de menos
vive en el host.*
| | `clawk down` | `clawk destroy` |
| --- | :---: | :---: |
| Tu repositorio (worktree montado; commits, ramas) | ✅ | ✅ |
| Estado del agente (conversaciones de Claude/Codex/pi/opencode, memoria) | ✅ | ✅ |
| El disco de la VM (instalaciones de apt, cachés, `$HOME`) | ❌ (se reconstruye desde cero en cada arranque*) | ❌ (esa es la idea) |
\* Dos excepciones: reanudar un `clawk snapshot` restaura el disco y la
memoria exactamente como se suspendieron, y el proveedor Linux/firecracker conserva
su disco hasta el destroy. Las herramientas que se necesitan en cada arranque pertenecen a la imagen
(`vm ( image … )`); la configuración por arranque pertenece a los hooks `on up`.
El estado del agente se monta desde el host por sandbox: el directorio home de cada runner —
el `~/.claude/` de claude, el `~/.codex/` de codex, el `~/.pi/` de pi, los dos directorios XDG de opencode
— viven bajo
`~/.clawk/namespaces/default/state/<name>/` en el host, de modo que un sandbox recreado
recupera sus conversaciones antiguas con `--resume`. Ese montaje es lo que
hace real la promesa: el disco de la VM en sí se vuelve a clonar desde la imagen en
cada arranque, así que cualquier cosa que un runner escriba fuera de esos directorios se pierde
en el siguiente `clawk up`.
## Autonomía total por defecto (y la opción de exclusión `--safe`)
Los runners se lanzan en sus modos "con sandbox externo": claude recibe
`--dangerously-skip-permissions`, codex recibe
`--dangerously-bypass-approvals-and-sandbox`, pi recibe `--approve` (no tiene
prompts de aprobación que eludir —no incluye ningún sandbox—, pero sí condiciona
la configuración y las extensiones locales del proyecto en `.pi/` tras un prompt de confianza), y
opencode recibe `--auto`. En tu propia máquina esos flags
serían temerarios; aquí son la idea: el límite de la VM y la lista
de permitidos de red proporcionan el confinamiento, así que el agente trabaja a plena velocidad sin
prompts por acción. El agente solo puede afectar a lo que hayas montado y
permitido en la lista, nada más (consulta [SECURITY.md](https://github.com/clawkwork/clawk/blob/main/SECURITY.md)).
¿Prefieres los prompts de confirmación de todos modos? Añade `--safe` a cualquier attach
(`clawk --safe`, `clawk run claude --safe`) y el runner se inicia sin sus
flags de omisión para esa sesión.
## Redes
El tráfico saliente se deniega por defecto; cada sandbox tiene su propia lista de permitidos.
DNS resuelve todo; TCP, UDP (incluido QUIC) e ICMP echo hacia hosts no listados
se rechazan. Los registros comunes (npm, PyPI, crates.io, GitHub,
Anthropic, …) están pre-permitidos, y el filtro tiene en cuenta el DNS, así que permitir
`example.com` sigue funcionando a medida que rotan sus IPs.
```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
```
Las denegaciones se registran por el *nombre de host que el invitado resolvió*, por lo que `clawk network
denials` se lee como un registro de lo que el agente intentó alcanzar. Las políticas nombradas reutilizables (incluida la suscripción a listas de bloqueo externas como oisd) y la cadena `use` que las superpone se encuentran en
**[docs/networking.md](https://github.com/clawkwork/clawk/blob/main/docs/networking.md)**.
## Configuración: `clawk.mod`
No se requiere ningún archivo de configuración; los valores predeterminados son razonables. Cuando un proyecto necesita
más, un archivo `clawk.mod` lo describe, con una sintaxis al estilo de 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."
)
)
```
El bloque es una *plantilla*: se captura como instantánea cuando se crea el sandbox, de modo que un sandbox en ejecución nunca cambia de forma inesperada. La referencia completa (shares, archivos secretos, skills, siembra de memoria del agente, raíces de espacio de trabajo multi-repo) está en **[docs/configuration.md](https://github.com/clawkwork/clawk/blob/main/docs/configuration.md)**; los servidores MCP y cómo sus credenciales se mantienen fuera del disco están en **[docs/mcp.md](https://github.com/clawkwork/clawk/blob/main/docs/mcp.md)**; cómo poner una placa USB-serial desde tu Mac dentro del sandbox para trabajo con microcontroladores está en **[docs/serial.md](https://github.com/clawkwork/clawk/blob/main/docs/serial.md)**; las imágenes y los kernels de invitado personalizados (incluido el kernel con KVM habilitado que se usa para virtualización anidada) están en **[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` es la hibernación para los sandboxes: la memoria del invitado se guarda junto a su disco y el siguiente arranque restaura el invitado exactamente donde estaba. Los procesos en segundo plano y los servidores de desarrollo continúan como si nada hubiera pasado, y `clawk attach` te devuelve frente al agente. La superficie completa de comandos, el despacho del runner y la maquinaria de gestión de inactividad (ballooning, control de admisión, auto-stop) están en **[docs/commands.md](https://github.com/clawkwork/clawk/blob/main/docs/commands.md)**.
## Cómo 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
```
Algunas decisiones deliberadas, en resumen:
- **El rootfs es una imagen OCI ordinaria.** clawk la descarga (sin demonio de Docker),
aplana las capas y escribe un disco ext4 directamente, sin root y sin
dispositivos loop. Cada sandbox de la misma imagen es un clon copy-on-write
(APFS `clonefile` / `FICLONE`), por lo que el coste de disco por sandbox es lo que el guest
escribe.
- **La red se filtra por debajo del guest.** Todo el L3 de la VM (gateway,
DHCP, DNS, NAT) es una pila en espacio de usuario dentro del proceso del demonio. Cada
conexión saliente y cada respuesta DNS consultan allí la lista de permitidos, donde
incluso root dentro del guest no puede cambiarla. Sin iptables en el host, sin sudo.
- **Una sola vía de entrada.** Sin sshd, sin cloud-init: un único agente vsock es la única
ruta de control hacia el guest, y cada attach es al estilo container-exec: un
proceso nuevo, destruido al desconectar.
El panorama completo (la pila del guest, ambos proveedores, la red a nivel de
tramas) está en **[ARCHITECTURE.md](https://github.com/clawkwork/clawk/blob/main/ARCHITECTURE.md)**, y el razonamiento
detrás de cada decisión en **[DESIGN.md](https://github.com/clawkwork/clawk/blob/main/DESIGN.md)**.
## Comparado con
- **Contenedores y devcontainers.** Comparten tu kernel y ven tu
sistema de archivos menos las reglas de denegación; un solo bug del kernel o un montaje equivocado puede
exponer el host. Las configuraciones de devcontainer a menudo montan el socket de Docker del host
para construir imágenes, entregando al contenedor el control del demonio del host;
clawk mantiene Docker *dentro* de la VM en su lugar. Y no hay
`Dockerfile`/`devcontainer.json` que escribir: cualquier imagen OCI es el rootfs.
- **Sandboxes de agentes a nivel de SO.** Herramientas como sandbox-runtime de Anthropic aplican
barreras a nivel de proceso en tu máquina real: geniales para reglas
ligeras, pero un error de política lo expone todo (incluido el keychain), y
las instalaciones, servicios en segundo plano o un hipervisor anidado son difíciles de permitir
de forma segura. clawk traslada toda la carga de trabajo a una máquina diferente.
- **Gestores de VM de propósito general (p. ej., Lima).** Lima te da una VM Linux;
clawk es un *flujo de trabajo* sobre una: una VM por proyecto con el repositorio
montado, un agente conectado y autenticado, egress en la lista de permitidos por
defecto y denegaciones registradas, conversaciones del agente persistidas entre destrucciones,
y un modo ticket que gestiona worktrees y PRs. (Bajo el capó ambos usan
Virtualization.framework.)
- **Sandboxes en la nube.** Local-first: tu código nunca sale de la máquina,
nada se factura por hora, y el worktree que edita el agente es el que
está en tu editor, montado en vivo en macOS (el proveedor Linux actualmente lo incorpora
en la creación; consulta [Roadmap](#roadmap)). Los sandboxes en la nube encajan en flotas;
clawk es para la máquina de tu escritorio.
## Modelo de seguridad (y sus límites)
Dos fronteras hacen el trabajo: la VM (el sistema de archivos del host es invisible excepto
lo que montes) y la lista de permitidos de salida (aplicada en espacio de usuario por debajo del
guest, para cada protocolo que pueda salir de él). Contra lo que clawk **no** protege:
- **Todo lo que montes o permitas queda expuesto.** Los worktrees son escribibles, así que un
agente puede hacer commit de código malo o hacer push a cualquier repositorio que tu ssh-agent reenviado pueda
alcanzar. Revisa lo que sale de un sandbox como revisarías el
PR de un desconocido.
- **Los secretos que introduces son visibles.** El contenido de `files ( … )` y `shares ( … )`,
las variables de entorno reenviadas y el token de Claude son legibles por el agente
(y, si un destino está en la lista de permitidos, enviables allí). Comparte lo mínimo.
- **Escapes del hipervisor.** clawk depende del aislamiento de Virtualization.framework/KVM;
no añade defensas más allá de ellos.
Si encuentras una forma de romper una frontera (escape de guest a host, bypass del filtro
de red, filtración de credenciales), repórtalo de forma privada mediante
[SECURITY.md](https://github.com/clawkwork/clawk/blob/main/SECURITY.md).
## FAQ
**¿Cuál es la sobrecarga?**
El primer arranque desde una imagen paga una construcción única del rootfs (pull → flatten →
ext4). Después de eso, los discos son clones copy-on-write y el kernel arranca directamente,
sin firmware y sin instalador. Las VM inactivas liberan memoria hasta ~1 GiB, se detienen
automáticamente tras 30 minutos de inactividad, y pueden tomarse snapshots a disco para que solo
cuesten almacenamiento.
**¿Funciona en Macs con Intel? ¿Windows?**
No. macOS requiere Apple silicon (macOS 14+). En Linux, el proveedor firecracker
funciona pero es experimental (ver
[docs/commands.md](https://github.com/clawkwork/clawk/blob/main/docs/commands.md#vm-providers)). No hay soporte para Windows.
**¿Necesito tener Docker instalado?**
No. clawk descarga imágenes OCI y construye discos de arranque por sí mismo. Las *imágenes*
de Docker son el formato de entrada; el motor de Docker no interviene. (Ejecutar un demonio
de Docker *dentro* de un sandbox es una función aparte, opcional; ver
[Images](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override) para los requisitos de hardware y kernel).
**¿Por qué "clawk"?**
La marca es una garra; *clawkwork* es un juego de palabras con *A Clockwork Orange*. Una VM que
das cuerda, sueltas y siempre puedes reiniciar.
## Hoja de ruta
Lo siguiente: ejecutar más sandboxes de los que tu RAM puede mantener a la vez.
- **Paradas por inactividad que crean snapshots.** La suspensión manual a disco se lanzó como
`clawk snapshot` / `clawk resume`; a continuación, la parada por inactividad *automática* también
la usará, para que los servidores de desarrollo sobrevivan a la parada y un sandbox suspendido cueste solo
disco.
- **Un límite de VMs en ejecución.** En lugar de rechazar una nueva VM cuando la RAM está
comprometida, suspender a disco el sandbox usado menos recientemente e iniciar el
nuevo.
- **Paridad con Firecracker.** Propagación de worktrees en vivo y envío de archivos del host en
Linux.
## Estado
Pre-1.0 y en desarrollo activo, y evolucionando rápidamente: espera cambios
disruptivos entre versiones. La superficie de la CLI cambia menos y los internos más,
pero nada está congelado hasta la 1.0.
## Contribuir
Los issues y PRs son bienvenidos. Ver [CONTRIBUTING.md](https://github.com/clawkwork/clawk/blob/main/CONTRIBUTING.md) para compilar
y probar, [ARCHITECTURE.md](https://github.com/clawkwork/clawk/blob/main/ARCHITECTURE.md) para saber cómo está construido, y
[DESIGN.md](https://github.com/clawkwork/clawk/blob/main/DESIGN.md) para saber hacia dónde se dirige.
## Licencia
[Apache License 2.0](https://github.com/clawkwork/clawk/blob/main/LICENSE). clawk incluye dos componentes de terceros bajo
sus propias licencias (gvisor-tap-vsock, Apache-2.0; un escritor ext4 de hcsshim, MIT);
ver [NOTICE](https://github.com/clawkwork/clawk/blob/main/NOTICE).