claw machine

claw machine le da a cualquier agente acceso al socket de Docker local del usuario.

Documentación

ClawMachine

Dale a cualquier IA un homelab. Servidor MCP para WAGMIOS — expone la gestión de Docker como herramientas del Protocolo de Contexto de Modelo (MCP) con claves API de alcance limitado.

Funciona con Claude Code, Cursor, GitHub Copilot, VS Code, Gemini y cualquier cliente compatible con MCP.

Por qué

Los agentes de IA que gestionan Docker necesitan acceso al socket de Docker, lo que implica acceso root completo en el host. Un solo docker rm incorrecto y los datos de producción desaparecen.

ClawMachine resuelve esto situándose entre la IA y Docker, enrutando todas las solicitudes a través de la API de alcance limitado de WAGMIOS:

Herramientas limitadas por alcance — Si la clave API no tiene containers:delete, la herramienta delete_container no existe. La IA literalmente no puede llamarla.
Registro de auditoría — Cada llamada a la API se rastrea por clave en WAGMIOS.
Multi-máquina — Un servidor MCP, múltiples instancias de WAGMIOS, cada una con su propia clave y alcances.

La IA nunca toca el socket de Docker. La IA nunca obtiene sudo. La aplicación de permisos está en la clave, no en el prompt.

Cómo funciona

┌──────────────┐     MCP (stdio/SSE)     ┌──────────────┐     REST (scoped key)    ┌──────────────┐     Docker API     ┌────────┐
│  AI Client   │ ───────────────────────→ │  ClawMachine │ ──────────────────────→ │   WAGMIOS    │ ────────────────→ │ Docker │
│ (Claude,etc) │                          │  MCP Server  │                         │  REST API    │                   │ Daemon │
└──────────────┘                          └──────────────┘                         └──────────────┘                   └────────┘

Instalas WAGMIOS en tu máquina y creas una clave API de alcance limitado
Ejecutas ClawMachine, apuntándolo a WAGMIOS con esa clave
ClawMachine lee los alcances de la clave y solo registra las herramientas que la clave permite
Tu cliente de IA ve un conjunto personalizado de herramientas de gestión de Docker — nada más

Inicio rápido

1. Instalar WAGMIOS

curl -O https://raw.githubusercontent.com/mentholmike/wagmios/main/docker-compose.yaml
docker compose up -d

WAGMIOS se ejecuta en http://localhost:5179 (API) y http://localhost:5174 (interfaz de usuario).

2. Crear una clave API

En la interfaz de WAGMIOS → Configuración → Permisos de agente:

Nombre: my-agent
Habilitar: containers:read, containers:write, images:read, marketplace:read, system:read
Deja containers:delete desactivado a menos que quieras que la IA pueda eliminar contenedores
Copia la clave: wag_live_abc123...

3. Instalar ClawMachine

Binario (Go):

go install github.com/mentholmike/clawmachine/cmd/clawmachine@latest

Docker:

docker run -i itzmizzle/clawmachine -api-url http://host.docker.internal:5179 -api-key wag_live_abc123

4. Configurar tu cliente de IA

Claude Code (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "clawmachine": {
      "command": "clawmachine",
      "args": ["-api-url", "http://localhost:5179", "-api-key", "wag_live_abc123"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "clawmachine": {
      "command": "clawmachine",
      "args": ["-api-url", "http://localhost:5179", "-api-key", "wag_live_abc123"]
    }
  }
}

Docker MCP Toolkit (Docker Desktop 4.62+):

{
  "servers": {
    "clawmachine": {
      "command": "docker",
      "args": ["run", "-i", "itzmizzle/clawmachine", "-api-url", "http://host.docker.internal:5179", "-api-key", "wag_live_abc123"],
      "type": "stdio"
    }
  }
}

5. Usarlo

You: "What containers am I running?"
→ list_containers
   "3 containers: nginx-proxy (running), postgres-db (running), jellyfin (stopped)"

You: "Delete postgres"
→ "I don't have a delete_container tool — your API key is missing the containers:delete scope."

You: "Install Ollama"
→ browse_marketplace → install_app → start_app
   "Ollama is installed and running on port 11434."

Herramientas

Las herramientas se registran dinámicamente según los alcances de la clave API. Si la clave no tiene el alcance requerido, la herramienta no existe.

Alcance requerido	Herramientas	Descripción
(cualquier clave)	`check_scopes`	Muestra la etiqueta de la clave, el prefijo y los alcances concedidos
`system:read`	`system_info`	Versión de Docker, versión de API, SO/arquitectura
`system:read`	`system_metrics`	Uso de CPU, memoria, disco, recuento de contenedores
`containers:read`	`list_containers`	Todos los contenedores (en ejecución + detenidos)
`containers:read`	`container_logs`	Salida de registros del contenedor (cola configurable)
`containers:read`	`container_config`	Configuración completa del contenedor (env, volúmenes, puertos)
`containers:write`	`start_container`	Iniciar un contenedor detenido
`containers:write`	`stop_container`	Detener un contenedor en ejecución
`containers:write`	`restart_container`	Reiniciar un contenedor
`containers:write`	`create_container`	Crear un nuevo contenedor (imagen, nombre, env, puertos, volúmenes)
`containers:delete`	`delete_container`	Eliminar permanentemente un contenedor (irreversible)
`images:read`	`list_images`	Todas las imágenes de Docker en el host
`images:write`	`pull_image`	Extraer una imagen de un registro
`images:write`	`delete_image`	Eliminar una imagen (irreversible)
`marketplace:read`	`browse_marketplace`	Explorar más de 34 aplicaciones autoalojadas
`marketplace:read`	`get_marketplace_app`	Detalles de la aplicación (descripción, categorías, compose)
`marketplace:read`	`list_installed_apps`	Aplicaciones instaladas a través del marketplace
`marketplace:write`	`install_app`	Descargar e instalar una aplicación del marketplace
`marketplace:write`	`start_app`	Iniciar una aplicación instalada (docker compose up)

Modo multi-instancia

Gestiona múltiples máquinas desde un solo servidor MCP. Crea un archivo de configuración:

{
  "instances": {
    "nas": {
      "url": "http://192.168.1.10:5179",
      "key": "wag_live_aaa",
      "label": "Homelab NAS"
    },
    "vps": {
      "url": "https://vps.example.com:5179",
      "key": "wag_live_bbb",
      "label": "VPS"
    }
  }
}

Ejecuta con:

clawmachine -config instances.json -transport sse -sse-addr :8080

En modo multi-instancia:

Cada herramienta recibe un parámetro host (por ejemplo, host="nas")
Una herramienta list_hosts muestra todas las instancias configuradas con etiquetas y alcances
La clave de cada host tiene sus propias restricciones de alcance: la clave del NAS puede tener containers:delete mientras que la clave del VPS no

You: "Restart Nginx on the NAS and check images on the VPS"
→ restart_container(host="nas", id="nginx-proxy")
→ list_images(host="vps")

Modos de transporte

Modo	Caso de uso	Comando
stdio	Clientes de IA locales (Claude Code, Cursor)	`clawmachine -api-url ... -api-key ...`
SSE	Clientes remotos, agentes basados en web	Añade `-transport sse -sse-addr :8080 -sse-base-url http://your-host:8080`

Variables de entorno

Las banderas se pueden configurar mediante variables de entorno:

WAGMIOS_API_URL — URL del backend de WAGMIOS
WAGMIOS_API_KEY — Clave API de WAGMIOS

Modelo de seguridad

	Acceso directo a Docker	ClawMachine + WAGMIOS
Permisos	Todo o nada	Alcances granulares por clave
Registro de auditoría	Registros del daemon de Docker (ruidosos)	Fuente de actividad de WAGMIOS (por clave)
Seguridad de eliminación	El agente puede `docker rm -f` cualquier cosa	La clave debe tener el alcance `containers:delete`
Multi-tenant	Un socket, todos comparten	Claves separadas, alcances separados
Radio de impacto	Host completo	Limitado a los permisos de la clave

La aplicación de permisos está en la clave, no en el prompt. Incluso si una IA decide llamar a delete_container sin preguntar, la llamada falla a nivel de la API de WAGMIOS si la clave no tiene el alcance.

Arquitectura

cmd/clawmachine/main.go       Entry point, single/multi routing
internal/config/
  config.go                    Single-instance config
  multi.go                     Multi-instance config loader
internal/wagmios/
  client.go                    WAGMIOS REST API client
internal/mcp/
  server.go                    Single-instance MCP server (18 tools)
  multi.go                     Multi-instance MCP server (19 tools)

Stack: Go 1.25, mcp-go v0.48.0, versión del protocolo MCP 2024-11-05

Docker

# Build
docker build -t itzmizzle/clawmachine .

# Run (stdio)
docker run -i itzmizzle/clawmachine -api-url http://host.docker.internal:5179 -api-key wag_live_xxx

# Run (SSE)
docker run -p 8080:8080 itzmizzle/clawmachine \
  -api-url http://host.docker.internal:5179 -api-key wag_live_xxx \
  -transport sse -sse-addr :8080 -sse-base-url http://localhost:8080

Las imágenes multi-arquitectura (amd64 + arm64) se compilan y se envían a itzmizzle/clawmachine en Docker Hub mediante GitHub Actions en cada push a main y en las etiquetas de versión.

Desarrollo

git clone https://github.com/mentholmike/clawmachine.git
cd clawmachine
go build ./cmd/clawmachine/
go vet ./...

Licencia

MIT

Relacionados

WAGMIOS — Plataforma de gestión de Docker autoalojada
mcp-go — SDK de MCP para Go
Docker MCP Catalog — Catálogo curado de servidores MCP