claw machine

claw machine dá a qualquer agente acesso ao socket Docker local do usuário.

Documentação

ClawMachine

Dê a qualquer IA um homelab. Servidor MCP para WAGMIOS — expõe o gerenciamento de Docker como ferramentas do Model Context Protocol com chaves de API com escopo.

Funciona com Claude Code, Cursor, GitHub Copilot, VS Code, Gemini e qualquer cliente compatível com MCP.

Por quê

Agentes de IA que gerenciam Docker precisam de acesso ao socket do Docker — o que significa acesso root total no host. Um único docker rm errado e os dados de produção desaparecem.

O ClawMachine resolve isso ficando entre a IA e o Docker, roteando todas as solicitações pela API com escopo do WAGMIOS:

Ferramentas com escopo limitado — Se a chave de API não tiver containers:delete, a ferramenta delete_container não existe. A IA literalmente não consegue chamá-la.
Trilha de auditoria — Cada chamada de API é rastreada por chave no WAGMIOS.
Multi-máquina — Um servidor MCP, várias instâncias do WAGMIOS, cada uma com sua própria chave e escopos.

A IA nunca toca no socket do Docker. A IA nunca recebe sudo. A aplicação está na chave, não no prompt.

Como Funciona

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

Você instala o WAGMIOS na sua máquina e cria uma chave de API com escopo
Você executa o ClawMachine, apontando-o para o WAGMIOS com essa chave
O ClawMachine lê os escopos da chave e registra apenas as ferramentas que a chave permite
Seu cliente de IA vê um conjunto personalizado de ferramentas de gerenciamento de Docker — nada além disso

Início Rápido

1. Instale o WAGMIOS

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

O WAGMIOS roda em http://localhost:5179 (API) e http://localhost:5174 (UI).

2. Crie uma Chave de API

Na UI do WAGMIOS → Configurações → Permissões de Agente:

Nome: my-agent
Ativar: containers:read, containers:write, images:read, marketplace:read, system:read
Deixe containers:delete desativado a menos que você queira que a IA possa remover contêineres
Copie a chave: wag_live_abc123...

3. Instale o ClawMachine

Binário (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. Configure Seu 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. Use

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."

Ferramentas

As ferramentas são registradas dinamicamente com base nos escopos da chave de API. Se a chave não tiver o escopo necessário, a ferramenta não existe.

Escopo Necessário	Ferramentas	Descrição
(qualquer chave)	`check_scopes`	Mostra o rótulo da chave, prefixo e escopos concedidos
`system:read`	`system_info`	Versão do Docker, versão da API, SO/arquitetura
`system:read`	`system_metrics`	Uso de CPU, memória, disco, contagem de contêineres
`containers:read`	`list_containers`	Todos os contêineres (em execução + parados)
`containers:read`	`container_logs`	Saída de logs do contêiner (cauda configurável)
`containers:read`	`container_config`	Configuração completa do contêiner (env, volumes, portas)
`containers:write`	`start_container`	Inicia um contêiner parado
`containers:write`	`stop_container`	Para um contêiner em execução
`containers:write`	`restart_container`	Reinicia um contêiner
`containers:write`	`create_container`	Cria um novo contêiner (imagem, nome, env, portas, volumes)
`containers:delete`	`delete_container`	Exclui permanentemente um contêiner (irreversível)
`images:read`	`list_images`	Todas as imagens Docker no host
`images:write`	`pull_image`	Baixa uma imagem de um registro
`images:write`	`delete_image`	Exclui uma imagem (irreversível)
`marketplace:read`	`browse_marketplace`	Navegue por 34+ aplicativos auto-hospedados
`marketplace:read`	`get_marketplace_app`	Detalhes do aplicativo (descrição, categorias, compose)
`marketplace:read`	`list_installed_apps`	Aplicativos instalados via marketplace
`marketplace:write`	`install_app`	Baixa e instala um aplicativo do marketplace
`marketplace:write`	`start_app`	Inicia um aplicativo instalado (docker compose up)

Modo Multi-Instância

Gerencie várias máquinas a partir de um único servidor MCP. Crie um arquivo de configuração:

{
  "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"
    }
  }
}

Execute com:

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

No modo multi-instância:

Cada ferramenta recebe um parâmetro host (ex.: host="nas")
Uma ferramenta list_hosts mostra todas as instâncias configuradas com rótulos e escopos
A chave de cada host tem suas próprias restrições de escopo — a chave do NAS pode ter containers:delete enquanto a chave do VPS não tem

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 locais (Claude Code, Cursor)	`clawmachine -api-url ... -api-key ...`
SSE	Clientes remotos, agentes baseados na web	Adicione `-transport sse -sse-addr :8080 -sse-base-url http://your-host:8080`

Variáveis de Ambiente

As flags podem ser definidas por meio de variáveis de ambiente:

WAGMIOS_API_URL — URL do backend do WAGMIOS
WAGMIOS_API_KEY — Chave de API do WAGMIOS

Modelo de Segurança

	Acesso Docker Bruto	ClawMachine + WAGMIOS
Permissões	Tudo ou nada	Escopos granulares por chave
Trilha de auditoria	Logs do daemon do Docker (ruidosos)	Feed de atividades do WAGMIOS (por chave)
Segurança de exclusão	O agente pode `docker rm -f` qualquer coisa	A chave deve ter escopo `containers:delete`
Multi-tenant	Um socket, todos compartilham	Chaves separadas, escopos separados
Raio de impacto	Host inteiro	Limitado às permissões da chave

A aplicação está na chave, não no prompt. Mesmo que uma IA decida chamar delete_container sem perguntar, a chamada falha no nível da API do WAGMIOS se a chave não tiver o escopo.

Arquitetura

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, versão do 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

Imagens multi-arquitetura (amd64 + arm64) são construídas e enviadas para itzmizzle/clawmachine no Docker Hub via GitHub Actions a cada push para main e em tags de versão.

Desenvolvimento

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

Licença

MIT

Relacionados

WAGMIOS — Plataforma de gerenciamento Docker auto-hospedada
mcp-go — SDK Go para MCP
Catálogo Docker MCP — Catálogo selecionado de servidores MCP