Guia de Despliegue de NanoClaw: Agente Claude Aislado en Contenedor en Tu VPS

NanoClaw me llamo la atencion porque maneja la seguridad de forma diferente a cualquier otro bot auto-alojado que he probado. En lugar de verificaciones de permisos a nivel de aplicacion, ejecuta cada agente en un contenedor Linux real. El agente solo puede ver lo que se monta explicitamente. Los comandos Bash se ejecutan dentro del contenedor, no en tu host. Tambien soporta Agent Swarms, donde multiples agentes trabajan juntos en la misma tarea.

Esta guia te lleva paso a paso para desplegar NanoClaw en un VPS con integracion de WhatsApp, tareas programadas y aislamiento adecuado en contenedores.

Si estas comparando opciones de bots auto-alojados, nuestro articulo de alternativas a OpenClaw incluye NanoClaw junto con ZeroClaw, nanobot, memU y PicoClaw.

Que es NanoClaw realmente

NanoClaw es una alternativa ligera a OpenClaw que se ejecuta sobre el Agent SDK de Claude. La diferencia clave con otros bots es el modelo de aislamiento. Los agentes se ejecutan en contenedores Linux (Docker en Linux/macOS, Apple Container en macOS) con directorios montados explicitamente. El agente no puede escapar del contenedor, y solo puede acceder a lo que tu permitas.

La arquitectura se ve asi:

WhatsApp (Baileys) --> SQLite --> Polling loop --> Container (Claude Agent SDK) --> Response

Un unico proceso Node.js. Colas de mensajes por grupo. IPC via sistema de archivos. Sin microservicios, sin colas de mensajes, sin capas de abstraccion. El codebase completo es lo suficientemente pequeño como para leerlo de una sentada.

Como se compara

Filosofia: Por que existe NanoClaw

OpenClaw tiene 52+ modulos, 8 archivos de gestion de configuracion, 45+ dependencias, y abstracciones para 15 proveedores de canales. Todo se ejecuta en un proceso Node con memoria compartida. La seguridad es a nivel de aplicacion — listas de permitidos y codigos de emparejamiento, no aislamiento a nivel de SO.

NanoClaw toma un enfoque diferente:

Lo suficientemente pequeño para entender. Un proceso, unos pocos archivos fuente. El codebase es lo suficientemente pequeño como para que Claude Code te lo explique y lo modifique de forma segura.

Seguro por aislamiento. Los agentes se ejecutan en contenedores Linux. Solo pueden ver lo que se monta explicitamente. El acceso a Bash es seguro porque los comandos se ejecutan dentro del contenedor, no en tu host.

Construido para un usuario. Esto no es un framework. Es software funcional que forkeas y haces que Claude Code personalice para tus necesidades exactas.

Nativo de IA. Sin asistente de instalacion. Claude Code guia la configuracion. Sin panel de monitoreo. Preguntale a Claude que esta pasando. Sin herramientas de depuracion. Describe el problema, Claude lo arregla.

Skills en lugar de funcionalidades. Los contribuidores no agregan funcionalidades al codebase. Contribuyen skills de Claude Code como /add-telegram que transforman tu fork. Terminas con codigo limpio que hace exactamente lo que necesitas.

Requisitos

Antes de empezar, asegurate de tener:

Para esta guia de despliegue en VPS, asumo Ubuntu 24.04 con Docker.

Instalacion

NanoClaw usa Claude Code para la configuracion. No hay un npm install o pip install como asistente. Clonas el repo y dejas que Claude se encargue de todo.

git clone https://github.com/qwibitai/NanoClaw.git
cd NanoClaw
claude

Luego ejecuta /setup. Claude Code se encarga de:

1. Instalar dependencias de Node.js
2. Autenticacion de WhatsApp
3. Deteccion y configuracion del runtime de contenedores
4. Configuracion del servicio
5. Configuracion inicial de skills

El proceso de configuracion es interactivo. Claude te hara preguntas y configurara todo basandose en tus respuestas.

Aislamiento en contenedores

Esta es la principal caracteristica que diferencia a NanoClaw. Los agentes se ejecutan en contenedores, no en el proceso principal.

Como funciona

Cuando envias un mensaje a NanoClaw:

1. El mensaje llega via WhatsApp (libreria Baileys)
2. El mensaje se almacena en SQLite con contexto de grupo
3. El bucle de polling recoge el mensaje
4. El container runner genera un contenedor aislado
5. El Claude Agent SDK procesa el mensaje dentro del contenedor
6. La respuesta se escribe en el sistema de archivos IPC
7. El proceso principal envia la respuesta de vuelta a WhatsApp

El contenedor no tiene acceso a red por defecto. Solo puede ver los directorios que montes explicitamente. Los comandos shell se ejecutan dentro del contenedor, asi que incluso si el agente intenta algo peligroso, esta contenido.

Configuracion de Docker

En Linux, NanoClaw usa Docker para el aislamiento en contenedores. El container runner genera un nuevo contenedor para cada invocacion del agente:

// src/container-runner.ts (simplified)
const container = await docker.createContainer({
  Image: 'nanoclaw-agent',
  Cmd: ['node', 'agent-entrypoint.js'],
  HostConfig: {
    Binds: [`${groupDir}:/workspace:rw`],
    NetworkMode: 'none', // No network by default
  },
});

Cada grupo tiene su propio directorio montado. El contenedor solo puede ver los archivos de ese grupo.

Apple Container (macOS)

En macOS, puedes opcionalmente cambiar a Apple Container para un runtime nativo mas ligero:

/convert-to-apple-container

Esto modifica la configuracion para usar el runtime de contenedores de Apple en lugar de Docker. El modelo de aislamiento es el mismo, pero la sobrecarga es menor en macOS.

Configuracion de WhatsApp

NanoClaw soporta WhatsApp, Telegram, Discord, Slack, Signal y operacion headless. WhatsApp via la libreria Baileys es el canal por defecto, con otros disponibles a traves de skills.

Autenticacion

Ejecuta el comando de configuracion en Claude Code:

/setup

Claude te guiara a traves de la autenticacion de WhatsApp. El proceso genera un codigo QR que escaneas con tu telefono:

1. Abre WhatsApp en tu telefono
2. Ve a Configuracion → Dispositivos vinculados
3. Toca “Vincular un dispositivo”
4. Escanea el codigo QR mostrado por NanoClaw

La sesion de autenticacion se almacena localmente. Permaneceras conectado hasta que cierres sesion explicitamente o la sesion expire.

Aislamiento de grupos

Cada grupo de WhatsApp tiene su propio contexto:

El canal principal (tu chat contigo mismo) es especial. Desde ahi puedes gestionar grupos y tareas:

@Andy list all scheduled tasks across groups
@Andy pause the Monday briefing task
@Andy join the Family Chat group

Palabra de activacion

Por defecto, el bot responde a @Andy. Cambiala diciendole a Claude Code:

Change the trigger word to @Bob

O ejecuta /customize para cambios guiados.

Agent Swarms

NanoClaw soporta Agent Swarms, donde multiples agentes se reparten el trabajo en una sola solicitud.

Que son los Agent Swarms

En lugar de que un agente maneje todo, puedes crear un equipo:

@Andy research the latest React patterns and have the code reviewer check if our codebase follows them

Esto podria generar:

• Agente investigador: Busca los ultimos patrones de React
• Agente revisor de codigo: Analiza tu codebase contra los patrones
• Coordinador: Sintetiza los hallazgos en una respuesta

Cada agente se ejecuta en su propio contenedor con acceso a las herramientas y archivos relevantes.

Configurar swarms

Los agent swarms se configuran a traves de skills. Dile a Claude Code que tipo de equipo quieres:

Create a swarm for daily news briefing with separate agents for:
- Tech news fetching
- AI news fetching  
- Summary writing

Claude creara los archivos de skill y la configuracion necesarios.

Sistema de skills

NanoClaw no usa archivos de configuracion para la personalizacion. Usa skills.

Que son los skills

Los skills son instrucciones que le enseñan a Claude Code como transformar tu instalacion de NanoClaw. Son archivos Markdown en .claude/skills/:

.claude/skills/
├── add-telegram/SKILL.md
├── customize/SKILL.md
├── setup/SKILL.md
└── ...

Skills incluidos

Personalizar comportamiento

No hay archivos de configuracion que aprender. Solo dile a Claude Code lo que quieres:

Change the trigger word to @Bob
Remember to make responses shorter and more direct
Add a custom greeting when I say good morning
Store conversation summaries weekly

El codebase es lo suficientemente pequeño como para que Claude pueda modificarlo de forma segura. Cada personalizacion se convierte en parte de tu fork.

Contribuir skills

No agregues funcionalidades. Agrega skills.

Si quieres agregar soporte para Telegram, no crees un PR que agregue Telegram junto a WhatsApp. En cambio, contribuye un archivo de skill que le enseñe a Claude Code como transformar una instalacion de NanoClaw para usar Telegram.

Los usuarios luego ejecutan /add-telegram en su fork y obtienen codigo limpio que hace exactamente lo que necesitan.

Tareas programadas

NanoClaw tiene un planificador de tareas integrado para trabajos recurrentes.

Crear tareas programadas

Dile al bot lo que quieres programar:

@Andy send an overview of the sales pipeline every weekday morning at 9am
@Andy review the git history for the past week each Friday and update the README if there's drift
@Andy every Monday at 8am, compile news on AI developments from Hacker News and TechCrunch and message me a briefing

El bot crea tareas programadas que ejecutan Claude y te pueden enviar mensajes de vuelta.

Gestionar tareas

Desde el canal principal (tu chat contigo mismo):

@Andy list all scheduled tasks across groups
@Andy pause the Monday briefing task
@Andy resume the Friday git review

Las tareas se almacenan en SQLite y persisten entre reinicios.

Sistema de memoria

Cada grupo tiene su propio archivo CLAUDE.md para memoria:

groups/
├── main/
│   └── CLAUDE.md
├── family-chat/
│   └── CLAUDE.md
└── work-team/
    └── CLAUDE.md

El agente lee este archivo al inicio de cada conversacion y puede actualizarlo. Dile que recuerde algo y lo escribe en el archivo.

Archivos de contexto

Como otros bots en este espacio, NanoClaw usa archivos de workspace para dar forma al comportamiento:

Estos son archivos Markdown simples que puedes editar directamente o hacer que Claude los modifique.

Modelo de seguridad

La seguridad de NanoClaw se basa en aislamiento a nivel de SO, no en verificaciones a nivel de aplicacion.

Sandboxing en contenedores

Incluso si el agente intenta ejecutar comandos peligrosos, esta contenido. El sistema host esta protegido.

Lo que aun deberias revisar

El aislamiento en contenedores es fuerte, pero aun deberias revisar:

1. Que directorios montas — Solo monta directorios que el agente realmente necesita
2. Que skills instalas — Los skills pueden modificar el codebase
3. Tareas programadas — Las tareas se ejecutan automaticamente con los permisos que tenga el agente

Ve docs/SECURITY.md en el repositorio para el modelo de seguridad completo.

Despliegue en VPS

Para uso en produccion en un VPS, aqui tienes una configuracion de despliegue completa.

Requisitos del servidor

NanoClaw en si es ligero. El principal consumidor de recursos es Docker para el aislamiento en contenedores.

Despliegue rapido

ssh root@YOUR_SERVER_IP

# Update system
apt update && apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com | sh
usermod -aG docker $USER

# Install Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Clone NanoClaw
git clone https://github.com/qwibitai/NanoClaw.git
cd NanoClaw

# Run setup
claude
# Then type: /setup

Servicio systemd

Crea un servicio systemd para inicio automatico:

cat > /etc/systemd/system/nanoclaw.service << 'EOF'
[Unit]
Description=NanoClaw AI Assistant
After=docker.service network.target

[Service]
Type=simple
User=dragos
WorkingDirectory=/home/dragos/nanoclaw
ExecStart=/usr/bin/node dist/index.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable nanoclaw
systemctl start nanoclaw

Variables de entorno

Crea un archivo .env con tus claves API:

ANTHROPIC_API_KEY=sk-ant-...

El proceso de configuracion te pedira esto, pero tambien puedes configurarlo manualmente.

Solucion de problemas

NanoClaw esta diseñado para depurarse a traves de Claude Code. Sin visores de logs ni paneles de depuracion.

Usando /debug

Si algo no funciona:

/debug

Claude Code analizara los logs, verificara la configuracion y sugerira soluciones. Si encuentra un problema que probablemente afecte a otros usuarios, puedes abrir un PR para modificar el skill de setup.

Problemas comunes

docker ps

journalctl -u nanoclaw -f

@Andy why isn't the scheduler running?

Analisis profundo de la arquitectura

Para quienes quieran entender el codebase:

src/
├── index.ts           # Orchestrator: state, message loop, agent invocation
├── channels/
│   └── whatsapp.ts    # WhatsApp connection, auth, send/receive
├── ipc.ts             # IPC watcher and task processing
├── router.ts          # Message formatting and outbound routing
├── group-queue.ts     # Per-group queue with global concurrency limit
├── container-runner.ts # Spawns streaming agent containers
├── task-scheduler.ts  # Runs scheduled tasks
└── db.ts              # SQLite operations (messages, groups, sessions, state)

Patrones clave:

• Proceso unico: Todo se ejecuta en un unico proceso Node.js
• Colas por grupo: Cada grupo tiene su propia cola de mensajes con control de concurrencia
• IPC via sistema de archivos: La comunicacion entre el proceso principal y los contenedores usa archivos
• Respuestas en streaming: La salida del contenedor se transmite de vuelta a WhatsApp en tiempo real

NanoClaw vs ZeroClaw vs nanobot

Uso los tres, asi que aqui va una comparacion directa:

NanoClaw gana en aislamiento y capacidades de agente. ZeroClaw es mas eficiente en recursos. nanobot tiene soporte mas amplio de canales y la configuracion mas facil.

/add-telegram
/add-slack
/add-discord

Si quieres una alternativa basada en Zig que se ejecuta en hardware de $5 con 22+ proveedores, ve nuestra guia de despliegue de NullClaw. Para una opcion basada en Python con soporte para MiniMax M2.5 y GLM-5, revisa la guia de configuracion de nanobot. Para recomendaciones de modelos que funcionan en estas plataformas, ve mejores modelos open source para OpenClaw.

Si quieres explorar otras herramientas de codificacion con IA, nuestra comparacion de herramientas de codificacion con IA cubre el panorama actual. Para conceptos basicos de MCP que funcionan en todos estos asistentes, revisa la introduccion a MCP para principiantes.

Este articulo tambien esta disponible en ingles: NanoClaw Deploy Guide