← Volver a agentes
v0.1.0latest0 weekly · 1 total downloads

nanobot

Asistente personal autoalojable en Python con WebUI, canales de chat, herramientas, memoria, MCP y automatizaciones. Guía práctica de instalación y operación.

Enlaces relacionados

Acerca del agente

nanobot — instalación y operación

Revisado: 10/10/2026
Repositorio: https://github.com/HKUDS/nanobot
Documentación primaria: instalación, despliegue, configuración, Telegram.

Compatibilidad: documentación oficial revisada el 10/10/2026, con v0.3.5 como referencia publicada. Comprueba nanobot --version: main puede describir funciones posteriores. Los ejemplos de administración del servidor son recomendaciones de despliegue.

1. Funciones

nanobot es un asistente autoalojable basado en Python, con interfaces web, terminal y mensajería. Gestiona sesiones, archivos, memoria y automatizaciones mediante herramientas y plugins. Puede desplegarse como asistente privado de Telegram con un modelo remoto.

Capacidades documentadas: WebUI, terminal/TUI, conversaciones y workspaces, presets y fallbacks de modelos, canales de mensajería, memoria, skills, cron/automations, MCP, web search/fetch, herramientas de archivo/shell, varias instancias, despliegue Docker/Compose, integración mediante Python SDK y API compatible con OpenAI. La disponibilidad exacta depende del canal, extra instalado, release y configuración.

2. Arquitectura conceptual

Telegram / WebUI / CLI / otros canales
               |
        gateway de nanobot
               |
       sesión + workspace
               |
      contexto / memoria / skills
               |
       LLM (API o local)
               |
    herramientas / MCP / web / shell
               |
       respuesta al canal
  • ~/.nanobot/config.json: configuración de modelos, herramientas, permisos, canales, WebUI y runtime.
  • ~/.nanobot/workspace/: memoria, skills, automations y artefactos de trabajo.
  • ~/.nanobot/sessions/<workspace-id>/: historial de sesiones separado del workspace.
  • Gateway: mantiene canales, trabajos recurrentes, sesiones y conectividad.
  • WebUI: se inicia normalmente con nanobot webui, por defecto en http://127.0.0.1:8765 para uso local.
  • Health del gateway: valor por defecto local 127.0.0.1:18790; API nanobot serve normalmente 8900. No se deben publicar por rutina.

Seguridad del diseño: una restricción por workspace aplicada por software no sustituye a un aislamiento de kernel. En Linux puedes activar tools.exec.sandbox: "bwrap", y en macOS "seatbelt"; la documentación indica que ninguno de esos dos backends aísla la red.

3. Requisitos y dimensionamiento

Requisitos confirmados

  • Python 3.11 o superior para la ruta Python.
  • Un proveedor y modelo válidos (API remota, endpoint corporativo o servidor local compatible).
  • Conexión saliente HTTPS desde la VPS hacia proveedor y hacia Telegram si lo usas.
  • Almacenamiento persistente para ~/.nanobot y backups.
  • Opcional: Docker Engine + Compose para despliegue contenedorizado; bubblewrap para sandbox Linux fuera del contenedor.

Dimensionamiento orientativo

  • Como punto de partida para una prueba con LLM remoto: 2 vCPU, 2–4 GB de RAM y 20 GB SSD. Es una estimación, no un mínimo oficial; ajusta según las mediciones.
  • Modelos locales, navegador y procesamiento de documentos aumentan los recursos necesarios. Dimensiona el modelo por tamaño y cuantización.
  • Monitoriza free -h, df -h, top/htop, tiempos de respuesta, reinicios, uso de tokens y gasto por proveedor. Establece límites de consumo a nivel de API.

4. Instalación local sencilla (Linux/macOS)

La documentación recomienda un instalador que elige virtualenv, uv, pipx o un entorno propio:

# Revisar antes de ejecutar: script remoto del repositorio oficial
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh -o /tmp/nanobot-install.sh
less /tmp/nanobot-install.sh
sh /tmp/nanobot-install.sh

# Alternativa reproducible por gestor:
uv tool install nanobot-ai
# o pipx install nanobot-ai

nanobot --version
nanobot onboard --wizard
nanobot status
nanobot agent -m "Hello!"

Si el ejecutable no está en PATH, el instalador indica cómo invocarlo; opciones documentadas:

uv tool run --from nanobot-ai nanobot --version
pipx run --spec nanobot-ai nanobot --version
~/.nanobot/venv/bin/python -m nanobot --version

No uses sudo pip install en el Python del sistema. Si el sistema marca externally-managed-environment, usa uv tool, pipx o venv.

Método Python con virtualenv (útil en VPS)

python3 --version        # 3.11+
python3 -m venv ~/venvs/nanobot
source ~/venvs/nanobot/bin/activate
python -m pip install --upgrade pip
python -m pip install nanobot-ai
nanobot --version
nanobot onboard --wizard
nanobot status
nanobot agent -m "Hello!"

La prueba agent -m realiza una llamada real al modelo si está configurado; status valida el estado local y no necesariamente llama a la API.

5. Despliegue VPS: ruta A — systemd (recomendada para un único bot personal)

Escenario: Ubuntu/Debian, acceso SSH, cuenta de servicio separada y proveedor LLM remoto. Revisa los cambios del sistema antes de aplicarlos.

5.1 Endurecer la máquina base

# Accede con tu usuario administrativo por SSH.
sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-venv python3-pip git curl ca-certificates

# Firewall: NO ejecutes sin antes confirmar que SSH funciona
sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status verbose

Comprueba python3 --version. Si es inferior a 3.11, instala una versión compatible desde tu distribución o un gestor de versiones de confianza.

Crea una cuenta separada (ejemplo nanobot, sin login root):

sudo adduser nanobot
sudo loginctl enable-linger nanobot
sudo -iu nanobot

Mantén la cuenta fuera de los grupos sudo y docker, con acceso solo a los datos y credenciales del servicio.

5.2 Instalar en virtualenv del usuario

python3 --version
python3 -m venv ~/.venvs/nanobot
~/.venvs/nanobot/bin/python -m pip install --upgrade pip
~/.venvs/nanobot/bin/python -m pip install nanobot-ai
~/.venvs/nanobot/bin/nanobot --version
~/.venvs/nanobot/bin/nanobot onboard --wizard

Inicializa ~/.nanobot/config.json, selecciona proveedor/modelo y realiza una primera prueba. Si no hay navegador en la VPS, usa el asistente terminal onboard --wizard o edita JSON manualmente (apartado 7).

5.3 Arrancar el servicio con el instalador oficial

~/.venvs/nanobot/bin/nanobot gateway install-service --manager systemd --dry-run
~/.venvs/nanobot/bin/nanobot gateway install-service --manager systemd
systemctl --user status nanobot-gateway
journalctl --user -u nanobot-gateway -f

Qué hace: crea ~/.config/systemd/user/nanobot-gateway.service, recarga el usuario systemd, habilita y reinicia el servicio. Usa el Python de la instalación desde la que llamaste al CLI. loginctl enable-linger nanobot permite que la unidad de usuario continúe tras cerrar SSH (necesita permisos administrativos).

Control diario:

systemctl --user restart nanobot-gateway
systemctl --user stop nanobot-gateway
systemctl --user start nanobot-gateway
journalctl --user -u nanobot-gateway --since "1 hour ago" --no-pager

No actives también nanobot gateway --background si el servicio systemd ya lo está ejecutando sobre la misma instancia: podrías tener dos procesos y puertos/sesiones en conflicto.

5.4 Cómo entrar a la WebUI desde tu portátil sin exponerla

En la VPS, el gateway/WebUI debe escuchar únicamente en loopback. Para acceder desde tu PC:

# EJECUTA EN TU ORDENADOR, NO EN LA VPS:
ssh -N -L 8765:127.0.0.1:8765 usuario@IP_O_HOST_DE_TU_VPS

Abre http://127.0.0.1:8765 en tu ordenador. Verifica en la VPS qué direcciones están escuchando:

ss -lntp | grep -E '8765|18790|8900'

Si escucha en 0.0.0.0:8765 o [::]:8765, revisa configuración y firewall. Para acceso remoto, utiliza el túnel SSH, una VPN privada o un proxy autenticado.

5.5 Variables secretas en systemd (propuesta operativa)

nanobot admite "${ENV_VAR}" en campos JSON. Puedes cargar claves mediante una unidad systemd de usuario:

mkdir -p ~/.config/nanobot
chmod 700 ~/.config/nanobot
install -m 600 /dev/null ~/.config/nanobot/secrets.env
nano ~/.config/nanobot/secrets.env

Configura las credenciales en el archivo privado:

PROVIDER_API_KEY=REEMPLAZAR
TELEGRAM_TOKEN=REEMPLAZAR

Edita la unidad generada:

systemctl --user edit nanobot-gateway

Añade:

[Service]
EnvironmentFile=%h/.config/nanobot/secrets.env

Después:

systemctl --user daemon-reload
systemctl --user restart nanobot-gateway
systemctl --user status nanobot-gateway

En el JSON, usa "${PROVIDER_API_KEY}" y "${TELEGRAM_TOKEN}". EnvironmentFile configura el servicio, no la terminal SSH; para pruebas de CLI, carga las variables por un gestor de secretos o un archivo shell privado. Mantén los valores fuera de logs.

6. Despliegue VPS: ruta B — Docker Compose

La documentación oficial ofrece Dockerfile, docker-compose.yml y un override para bwrap. Esta ruta requiere clonar el repo porque Compose construye desde ese checkout. Recomendación: fija una etiqueta/commit revisado si buscas reproducibilidad, y evalúa las actualizaciones antes de usar main.

# En VPS, con Docker Engine + Compose plugin ya instalados:
git clone https://github.com/HKUDS/nanobot.git
cd nanobot

git rev-parse --short HEAD    # registra este hash
# Instala dependencias de Telegram dentro de la imagen:
NANOBOT_CHANNELS=telegram docker compose build

docker compose run --rm nanobot-cli onboard
# Edita ~/.nanobot/config.json del usuario que ejecuta compose:
chmod 700 ~/.nanobot
chmod 600 ~/.nanobot/config.json
nano ~/.nanobot/config.json

docker compose run --rm nanobot-cli agent -m "Hello!"
docker compose up -d nanobot-gateway
docker compose ps
docker compose logs -f nanobot-gateway

Persistencia: el Compose oficial monta ~/.nanobot del host en /home/nanobot/.nanobot. El contenedor ejecuta el proceso final con usuario sin privilegios, UID 1000, y usa ciertas capacidades para ajustar el propietario del bind mount al iniciar. Revisa permisos de archivos antes de restaurar backups.

Exposición de puertos: revisa docker compose config y los ports: efectivos. Si una publicación sale en 0.0.0.0, cámbiala para restringirla a 127.0.0.1 o elimínala si vas a usar solo Telegram long polling. No asumas que Docker respetará todas las reglas UFW como los procesos normales: revisa reglas Docker, cortafuegos del proveedor y pruebas externas.

Si necesitas sandbox de comandos Linux dentro del contenedor:

# Sólo después de establecer tools.exec.sandbox=bwrap en config.json:
docker compose -f docker-compose.yml -f docker-compose.bwrap.yml up -d nanobot-gateway

El override habilita namespaces y desactiva perfiles AppArmor/seccomp. Evalúa ese cambio de protección antes de activarlo; requiere soporte de namespaces de usuario sin privilegios en el host.

Comandos operativos:

docker compose logs --tail=100 nanobot-gateway
docker compose restart nanobot-gateway
docker compose down  # detiene, no debería borrar bind mount

Evita montar el socket Docker dentro del agente; sería una vía para comprometer el host. No ejecutes el contenedor con --privileged por comodidad.

7. Configuración del proveedor/modelo (ejemplo genérico)

Configura el modelo desde WebUI → Settings → Models o nanobot onboard --wizard. Para configuración manual, integra este fragmento en el JSON existente:

{
  "providers": {
    "custom": {
      "apiKey": "${PROVIDER_API_KEY}",
      "apiBase": "https://api.tu-proveedor-ejemplo.com/v1"
    }
  },
  "modelPresets": {
    "primary": {
      "provider": "custom",
      "model": "ID-REAL-DEL-MODELO"
    }
  },
  "agents": {
    "defaults": {
      "modelPreset": "primary"
    }
  }
}

Ajusta proveedor, endpoint, modelo y clave como un conjunto. Consulta la documentación para presets, fallbacks y proveedores compatibles con OpenAI.

Validación:

nanobot status
nanobot agent -m "Resume en una frase qué puedes hacer."

Si no tienes el binario en PATH, usa su ruta absoluta, según instalación.

8. Telegram: alta, pairing y uso privado

Telegram funciona por long polling por defecto, así que para el piloto normalmente no necesitas un webhook público ni abrir puertos entrantes.

  1. En Telegram abre @BotFather, crea bot con /newbot, copia el token a tu gestor seguro.

  2. En el mismo Python/venv de nanobot activa el extra/plugin:

    nanobot plugins enable telegram
    
  3. Usa WebUI → Settings → Channels → Telegram, o añade manualmente a ~/.nanobot/config.json:

    {
      "channels": {
        "telegram": {
          "enabled": true,
          "token": "${TELEGRAM_TOKEN}"
        }
      }
    }
    
  4. No configures allowFrom: ["*"]. Al omitir allowFrom, el canal entra en modo de pairing según la guía oficial.

  5. Reinicia el gateway y comprueba nanobot channels status.

  6. Escribe un DM al bot desde tu cuenta; al recibir un código de pairing, apruébalo desde una superficie ya confiable:

    nanobot agent -m "/pairing approve ABCD-EFGH"
    
  7. Repite el mensaje: debe responder normalmente. Nunca aceptes por chat una orden de aprobación de un usuario aún no autorizado.

Para grupos: revisa quién puede mencionar el bot, cómo maneja adjuntos/enlaces y si tiene permiso de ejecución. Restringe la ejecución de herramientas a remitentes autorizados. Si el token se filtró, revócalo en BotFather y actualiza el servicio.

9. Herramientas, MCP y automatizaciones

Herramientas integradas

  • File/workspace: lectura/escritura limitable al área de trabajo. Evita dar acceso al home del usuario de sistema.
  • Shell (tools.exec): potente, pero de alto riesgo. Puedes desactivarla por completo con "tools": {"exec": {"enable": false}} fusionado en tu configuración. También admite timeout y sandbox.
  • Web: búsqueda/fetch y controles SSRF; las páginas externas pueden contener instrucciones maliciosas dirigidas al agente.
  • MCP: configuración bajo tools.mcpServers.<nombre> para servidores stdio o HTTP/SSE, según documentación. Un MCP de terceros equivale a instalar software con permisos: revisa su autor y alcance.
  • Skills: capacidad de ampliar comportamiento; revisa cualquier script ejecutable que incorporen.

Fragmento de endurecimiento inicial (Linux)

El siguiente es un fragmento para integrar, no un JSON completo:

{
  "tools": {
    "restrictToWorkspace": true,
    "exec": {
      "sandbox": "bwrap",
      "timeout": 60
    }
  }
}

Para instalar bubblewrap (host, sin Docker):

sudo apt install bubblewrap

Advertencia: con Docker, activar bwrap exige considerar el override descrito arriba. Si aún no has revisado esos permisos, es preferible deshabilitar exec en el primer despliegue. El sandbox no bloquea tráfico de red ni garantiza inmunidad frente a vulnerabilidades.

MCP ilustrativo

La documentación oficial muestra el concepto:

{
  "tools": {
    "mcpServers": {
      "mi-servidor": {
        "command": "npx",
        "args": ["-y", "PAQUETE_MCP_REVISADO"],
        "env": { "API_KEY": "${API_KEY_DEL_MCP}" }
      }
    }
  }
}

No copies sin revisar paquetes npx -y desde Internet en una VPS crítica: fija versión, controla dependencias y permisos de API. Para HTTP/SSE usa endpoint HTTPS, credenciales propias y política de egress.

Automations y heartbeat

Desde la WebUI se pueden crear tareas programadas y ver resultados; la documentación dedica una sección a cron, heartbeat y acciones de agente. Para la primera puesta en producción:

  1. Programa una tarea inocua (resumen de un archivo de prueba, una vez al día).
  2. Comprueba que se ejecuta tras cerrar SSH/reiniciar el servicio.
  3. Comprueba la zona horaria efectiva del servicio y de la tarea.
  4. Define timeout, límite de peticiones y presupuesto API.
  5. No programes escrituras destructivas sin revisión explícita.

Documentación: https://github.com/HKUDS/nanobot/blob/main/docs/automations.md

10. Permisos y límites de aislamiento

El workspace y las restricciones de la aplicación no constituyen una frontera del kernel. bwrap y seatbelt tampoco aíslan la red. Para datos de usuarios independientes, separa cuentas, credenciales y entornos según el nivel de confianza.

Restringe la salida a servicios necesarios y bloquea el acceso a metadatos de nube y redes internas. Mantén tools.ssrfWhitelist vacía salvo excepciones justificadas. Un agente con lectura de secretos y salida de red puede exfiltrarlos incluso dentro de un contenedor.

Revisa scripts de skills y MCP, y trata mensajes, documentos y páginas externas como entradas no confiables. Conserva logs y cambios de archivos con una política de retención adecuada.

11. Operación, backup y recuperación

Observabilidad

nanobot --version
nanobot status
nanobot channels status
nanobot gateway status
nanobot gateway logs

# si usas systemd:
systemctl --user status nanobot-gateway
journalctl --user -u nanobot-gateway -n 100 --no-pager

# si usas Compose:
docker compose ps
docker compose logs --tail=100 nanobot-gateway

nanobot gateway status/logs corresponden al modo en background del propio CLI; con systemd o Compose conviene usar el supervisor real.

Backup seguro (propuesta operativa)

Con el servicio parado, guarda ~/.nanobot (incluye config, sesiones, workspace y, potencialmente, secretos). Ejemplo conceptual:

systemctl --user stop nanobot-gateway
umask 077
tar -czf "$HOME/nanobot-backup-$(date +%F).tar.gz" -C "$HOME" .nanobot
systemctl --user start nanobot-gateway

Cifra el TAR antes de transferirlo, restringe sus permisos y prueba la restauración en otro entorno. Respalda ~/.config/nanobot/secrets.env por separado: está fuera de la carpeta ~/.nanobot.

Actualización controlada

# Si se instaló con uv:
uv tool upgrade nanobot-ai
# Si se instaló con pipx:
pipx upgrade nanobot-ai
# Si usa virtualenv:
~/.venvs/nanobot/bin/python -m pip install -U nanobot-ai

Después compara nanobot --version, relee release notes, reinicia servicio, prueba Telegram, pruebas de pairing, sandbox y automations. Para git/Compose, fija commit, haz backup y reconstruye con docker compose build y up -d tras revisar cambios. No hagas actualizaciones de main desatendidas en producción.

Troubleshooting (orden de diagnóstico)

SíntomaQué comprobar primero
nanobot: command not foundPATH, venv, runner uv/pipx, instalación como usuario correcto
status OK pero no respondecredencial del proveedor, ID de modelo, endpoint, red saliente, cuotas
Telegram sin mensajeschannels status, token, plugin en el mismo venv, gateway vivo, conectividad
Recibo código pero no accesoaprobar pairing desde CLI/superficie autorizada
WebUI inaccesible por SSHservicio escuchando, ssh -L, puerto local ocupado, bind loopback
Herramientas no leen archivosworkspace seleccionado, permisos Unix, restrictToWorkspace, rutas sandbox
bwrap falla con Operation not permittednamespaces de usuario, política del host, seccomp/Compose override
automations no se ejecutanservicio persistente, zona horaria, logs, cron, permisos de tarea
sube consumo/tokenssesiones acumuladas, concurrencia, bucles de herramienta, modelo elegido

12. Validación del despliegue

  • Prueba respuesta CLI y Telegram, y rechazo de remitentes no autorizados.
  • Comprueba continuidad al cerrar SSH, exposición de puertos y permisos de herramientas.
  • Ejecuta una tarea programada de prueba; mide recursos, latencia y consumo API.
  • Restaura un backup y registra cuenta, rutas, supervisor y versión desplegada.

13. Referencias oficiales

  1. README del proyecto
  2. Instalación y Quick Start
  3. Deployment — Compose, Docker, systemd, LaunchAgent
  4. Configuration — modelos, secretos, tools, sandbox, MCP
  5. Conectar Telegram y pairing
  6. Automations
  7. Guía segura de agente local
Ficheros y descargas

nanobot — instalación y operación

Revisado: 10/10/2026
Repositorio: https://github.com/HKUDS/nanobot
Documentación primaria: instalación, despliegue, configuración, Telegram.

Compatibilidad: documentación oficial revisada el 10/10/2026, con v0.3.5 como referencia publicada. Comprueba nanobot --version: main puede describir funciones posteriores. Los ejemplos de administración del servidor son recomendaciones de despliegue.

1. Funciones

nanobot es un asistente autoalojable basado en Python, con interfaces web, terminal y mensajería. Gestiona sesiones, archivos, memoria y automatizaciones mediante herramientas y plugins. Puede desplegarse como asistente privado de Telegram con un modelo remoto.

Capacidades documentadas: WebUI, terminal/TUI, conversaciones y workspaces, presets y fallbacks de modelos, canales de mensajería, memoria, skills, cron/automations, MCP, web search/fetch, herramientas de archivo/shell, varias instancias, despliegue Docker/Compose, integración mediante Python SDK y API compatible con OpenAI. La disponibilidad exacta depende del canal, extra instalado, release y configuración.

2. Arquitectura conceptual

Telegram / WebUI / CLI / otros canales
               |
        gateway de nanobot
               |
       sesión + workspace
               |
      contexto / memoria / skills
               |
       LLM (API o local)
               |
    herramientas / MCP / web / shell
               |
       respuesta al canal
  • ~/.nanobot/config.json: configuración de modelos, herramientas, permisos, canales, WebUI y runtime.
  • ~/.nanobot/workspace/: memoria, skills, automations y artefactos de trabajo.
  • ~/.nanobot/sessions/<workspace-id>/: historial de sesiones separado del workspace.
  • Gateway: mantiene canales, trabajos recurrentes, sesiones y conectividad.
  • WebUI: se inicia normalmente con nanobot webui, por defecto en http://127.0.0.1:8765 para uso local.
  • Health del gateway: valor por defecto local 127.0.0.1:18790; API nanobot serve normalmente 8900. No se deben publicar por rutina.

Seguridad del diseño: una restricción por workspace aplicada por software no sustituye a un aislamiento de kernel. En Linux puedes activar tools.exec.sandbox: "bwrap", y en macOS "seatbelt"; la documentación indica que ninguno de esos dos backends aísla la red.

3. Requisitos y dimensionamiento

Requisitos confirmados

  • Python 3.11 o superior para la ruta Python.
  • Un proveedor y modelo válidos (API remota, endpoint corporativo o servidor local compatible).
  • Conexión saliente HTTPS desde la VPS hacia proveedor y hacia Telegram si lo usas.
  • Almacenamiento persistente para ~/.nanobot y backups.
  • Opcional: Docker Engine + Compose para despliegue contenedorizado; bubblewrap para sandbox Linux fuera del contenedor.

Dimensionamiento orientativo

  • Como punto de partida para una prueba con LLM remoto: 2 vCPU, 2–4 GB de RAM y 20 GB SSD. Es una estimación, no un mínimo oficial; ajusta según las mediciones.
  • Modelos locales, navegador y procesamiento de documentos aumentan los recursos necesarios. Dimensiona el modelo por tamaño y cuantización.
  • Monitoriza free -h, df -h, top/htop, tiempos de respuesta, reinicios, uso de tokens y gasto por proveedor. Establece límites de consumo a nivel de API.

4. Instalación local sencilla (Linux/macOS)

La documentación recomienda un instalador que elige virtualenv, uv, pipx o un entorno propio:

# Revisar antes de ejecutar: script remoto del repositorio oficial
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh -o /tmp/nanobot-install.sh
less /tmp/nanobot-install.sh
sh /tmp/nanobot-install.sh

# Alternativa reproducible por gestor:
uv tool install nanobot-ai
# o pipx install nanobot-ai

nanobot --version
nanobot onboard --wizard
nanobot status
nanobot agent -m "Hello!"

Si el ejecutable no está en PATH, el instalador indica cómo invocarlo; opciones documentadas:

uv tool run --from nanobot-ai nanobot --version
pipx run --spec nanobot-ai nanobot --version
~/.nanobot/venv/bin/python -m nanobot --version

No uses sudo pip install en el Python del sistema. Si el sistema marca externally-managed-environment, usa uv tool, pipx o venv.

Método Python con virtualenv (útil en VPS)

python3 --version        # 3.11+
python3 -m venv ~/venvs/nanobot
source ~/venvs/nanobot/bin/activate
python -m pip install --upgrade pip
python -m pip install nanobot-ai
nanobot --version
nanobot onboard --wizard
nanobot status
nanobot agent -m "Hello!"

La prueba agent -m realiza una llamada real al modelo si está configurado; status valida el estado local y no necesariamente llama a la API.

5. Despliegue VPS: ruta A — systemd (recomendada para un único bot personal)

Escenario: Ubuntu/Debian, acceso SSH, cuenta de servicio separada y proveedor LLM remoto. Revisa los cambios del sistema antes de aplicarlos.

5.1 Endurecer la máquina base

# Accede con tu usuario administrativo por SSH.
sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-venv python3-pip git curl ca-certificates

# Firewall: NO ejecutes sin antes confirmar que SSH funciona
sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status verbose

Comprueba python3 --version. Si es inferior a 3.11, instala una versión compatible desde tu distribución o un gestor de versiones de confianza.

Crea una cuenta separada (ejemplo nanobot, sin login root):

sudo adduser nanobot
sudo loginctl enable-linger nanobot
sudo -iu nanobot

Mantén la cuenta fuera de los grupos sudo y docker, con acceso solo a los datos y credenciales del servicio.

5.2 Instalar en virtualenv del usuario

python3 --version
python3 -m venv ~/.venvs/nanobot
~/.venvs/nanobot/bin/python -m pip install --upgrade pip
~/.venvs/nanobot/bin/python -m pip install nanobot-ai
~/.venvs/nanobot/bin/nanobot --version
~/.venvs/nanobot/bin/nanobot onboard --wizard

Inicializa ~/.nanobot/config.json, selecciona proveedor/modelo y realiza una primera prueba. Si no hay navegador en la VPS, usa el asistente terminal onboard --wizard o edita JSON manualmente (apartado 7).

5.3 Arrancar el servicio con el instalador oficial

~/.venvs/nanobot/bin/nanobot gateway install-service --manager systemd --dry-run
~/.venvs/nanobot/bin/nanobot gateway install-service --manager systemd
systemctl --user status nanobot-gateway
journalctl --user -u nanobot-gateway -f

Qué hace: crea ~/.config/systemd/user/nanobot-gateway.service, recarga el usuario systemd, habilita y reinicia el servicio. Usa el Python de la instalación desde la que llamaste al CLI. loginctl enable-linger nanobot permite que la unidad de usuario continúe tras cerrar SSH (necesita permisos administrativos).

Control diario:

systemctl --user restart nanobot-gateway
systemctl --user stop nanobot-gateway
systemctl --user start nanobot-gateway
journalctl --user -u nanobot-gateway --since "1 hour ago" --no-pager

No actives también nanobot gateway --background si el servicio systemd ya lo está ejecutando sobre la misma instancia: podrías tener dos procesos y puertos/sesiones en conflicto.

5.4 Cómo entrar a la WebUI desde tu portátil sin exponerla

En la VPS, el gateway/WebUI debe escuchar únicamente en loopback. Para acceder desde tu PC:

# EJECUTA EN TU ORDENADOR, NO EN LA VPS:
ssh -N -L 8765:127.0.0.1:8765 usuario@IP_O_HOST_DE_TU_VPS

Abre http://127.0.0.1:8765 en tu ordenador. Verifica en la VPS qué direcciones están escuchando:

ss -lntp | grep -E '8765|18790|8900'

Si escucha en 0.0.0.0:8765 o [::]:8765, revisa configuración y firewall. Para acceso remoto, utiliza el túnel SSH, una VPN privada o un proxy autenticado.

5.5 Variables secretas en systemd (propuesta operativa)

nanobot admite "${ENV_VAR}" en campos JSON. Puedes cargar claves mediante una unidad systemd de usuario:

mkdir -p ~/.config/nanobot
chmod 700 ~/.config/nanobot
install -m 600 /dev/null ~/.config/nanobot/secrets.env
nano ~/.config/nanobot/secrets.env

Configura las credenciales en el archivo privado:

PROVIDER_API_KEY=REEMPLAZAR
TELEGRAM_TOKEN=REEMPLAZAR

Edita la unidad generada:

systemctl --user edit nanobot-gateway

Añade:

[Service]
EnvironmentFile=%h/.config/nanobot/secrets.env

Después:

systemctl --user daemon-reload
systemctl --user restart nanobot-gateway
systemctl --user status nanobot-gateway

En el JSON, usa "${PROVIDER_API_KEY}" y "${TELEGRAM_TOKEN}". EnvironmentFile configura el servicio, no la terminal SSH; para pruebas de CLI, carga las variables por un gestor de secretos o un archivo shell privado. Mantén los valores fuera de logs.

6. Despliegue VPS: ruta B — Docker Compose

La documentación oficial ofrece Dockerfile, docker-compose.yml y un override para bwrap. Esta ruta requiere clonar el repo porque Compose construye desde ese checkout. Recomendación: fija una etiqueta/commit revisado si buscas reproducibilidad, y evalúa las actualizaciones antes de usar main.

# En VPS, con Docker Engine + Compose plugin ya instalados:
git clone https://github.com/HKUDS/nanobot.git
cd nanobot

git rev-parse --short HEAD    # registra este hash
# Instala dependencias de Telegram dentro de la imagen:
NANOBOT_CHANNELS=telegram docker compose build

docker compose run --rm nanobot-cli onboard
# Edita ~/.nanobot/config.json del usuario que ejecuta compose:
chmod 700 ~/.nanobot
chmod 600 ~/.nanobot/config.json
nano ~/.nanobot/config.json

docker compose run --rm nanobot-cli agent -m "Hello!"
docker compose up -d nanobot-gateway
docker compose ps
docker compose logs -f nanobot-gateway

Persistencia: el Compose oficial monta ~/.nanobot del host en /home/nanobot/.nanobot. El contenedor ejecuta el proceso final con usuario sin privilegios, UID 1000, y usa ciertas capacidades para ajustar el propietario del bind mount al iniciar. Revisa permisos de archivos antes de restaurar backups.

Exposición de puertos: revisa docker compose config y los ports: efectivos. Si una publicación sale en 0.0.0.0, cámbiala para restringirla a 127.0.0.1 o elimínala si vas a usar solo Telegram long polling. No asumas que Docker respetará todas las reglas UFW como los procesos normales: revisa reglas Docker, cortafuegos del proveedor y pruebas externas.

Si necesitas sandbox de comandos Linux dentro del contenedor:

# Sólo después de establecer tools.exec.sandbox=bwrap en config.json:
docker compose -f docker-compose.yml -f docker-compose.bwrap.yml up -d nanobot-gateway

El override habilita namespaces y desactiva perfiles AppArmor/seccomp. Evalúa ese cambio de protección antes de activarlo; requiere soporte de namespaces de usuario sin privilegios en el host.

Comandos operativos:

docker compose logs --tail=100 nanobot-gateway
docker compose restart nanobot-gateway
docker compose down  # detiene, no debería borrar bind mount

Evita montar el socket Docker dentro del agente; sería una vía para comprometer el host. No ejecutes el contenedor con --privileged por comodidad.

7. Configuración del proveedor/modelo (ejemplo genérico)

Configura el modelo desde WebUI → Settings → Models o nanobot onboard --wizard. Para configuración manual, integra este fragmento en el JSON existente:

{
  "providers": {
    "custom": {
      "apiKey": "${PROVIDER_API_KEY}",
      "apiBase": "https://api.tu-proveedor-ejemplo.com/v1"
    }
  },
  "modelPresets": {
    "primary": {
      "provider": "custom",
      "model": "ID-REAL-DEL-MODELO"
    }
  },
  "agents": {
    "defaults": {
      "modelPreset": "primary"
    }
  }
}

Ajusta proveedor, endpoint, modelo y clave como un conjunto. Consulta la documentación para presets, fallbacks y proveedores compatibles con OpenAI.

Validación:

nanobot status
nanobot agent -m "Resume en una frase qué puedes hacer."

Si no tienes el binario en PATH, usa su ruta absoluta, según instalación.

8. Telegram: alta, pairing y uso privado

Telegram funciona por long polling por defecto, así que para el piloto normalmente no necesitas un webhook público ni abrir puertos entrantes.

  1. En Telegram abre @BotFather, crea bot con /newbot, copia el token a tu gestor seguro.

  2. En el mismo Python/venv de nanobot activa el extra/plugin:

    nanobot plugins enable telegram
    
  3. Usa WebUI → Settings → Channels → Telegram, o añade manualmente a ~/.nanobot/config.json:

    {
      "channels": {
        "telegram": {
          "enabled": true,
          "token": "${TELEGRAM_TOKEN}"
        }
      }
    }
    
  4. No configures allowFrom: ["*"]. Al omitir allowFrom, el canal entra en modo de pairing según la guía oficial.

  5. Reinicia el gateway y comprueba nanobot channels status.

  6. Escribe un DM al bot desde tu cuenta; al recibir un código de pairing, apruébalo desde una superficie ya confiable:

    nanobot agent -m "/pairing approve ABCD-EFGH"
    
  7. Repite el mensaje: debe responder normalmente. Nunca aceptes por chat una orden de aprobación de un usuario aún no autorizado.

Para grupos: revisa quién puede mencionar el bot, cómo maneja adjuntos/enlaces y si tiene permiso de ejecución. Restringe la ejecución de herramientas a remitentes autorizados. Si el token se filtró, revócalo en BotFather y actualiza el servicio.

9. Herramientas, MCP y automatizaciones

Herramientas integradas

  • File/workspace: lectura/escritura limitable al área de trabajo. Evita dar acceso al home del usuario de sistema.
  • Shell (tools.exec): potente, pero de alto riesgo. Puedes desactivarla por completo con "tools": {"exec": {"enable": false}} fusionado en tu configuración. También admite timeout y sandbox.
  • Web: búsqueda/fetch y controles SSRF; las páginas externas pueden contener instrucciones maliciosas dirigidas al agente.
  • MCP: configuración bajo tools.mcpServers.<nombre> para servidores stdio o HTTP/SSE, según documentación. Un MCP de terceros equivale a instalar software con permisos: revisa su autor y alcance.
  • Skills: capacidad de ampliar comportamiento; revisa cualquier script ejecutable que incorporen.

Fragmento de endurecimiento inicial (Linux)

El siguiente es un fragmento para integrar, no un JSON completo:

{
  "tools": {
    "restrictToWorkspace": true,
    "exec": {
      "sandbox": "bwrap",
      "timeout": 60
    }
  }
}

Para instalar bubblewrap (host, sin Docker):

sudo apt install bubblewrap

Advertencia: con Docker, activar bwrap exige considerar el override descrito arriba. Si aún no has revisado esos permisos, es preferible deshabilitar exec en el primer despliegue. El sandbox no bloquea tráfico de red ni garantiza inmunidad frente a vulnerabilidades.

MCP ilustrativo

La documentación oficial muestra el concepto:

{
  "tools": {
    "mcpServers": {
      "mi-servidor": {
        "command": "npx",
        "args": ["-y", "PAQUETE_MCP_REVISADO"],
        "env": { "API_KEY": "${API_KEY_DEL_MCP}" }
      }
    }
  }
}

No copies sin revisar paquetes npx -y desde Internet en una VPS crítica: fija versión, controla dependencias y permisos de API. Para HTTP/SSE usa endpoint HTTPS, credenciales propias y política de egress.

Automations y heartbeat

Desde la WebUI se pueden crear tareas programadas y ver resultados; la documentación dedica una sección a cron, heartbeat y acciones de agente. Para la primera puesta en producción:

  1. Programa una tarea inocua (resumen de un archivo de prueba, una vez al día).
  2. Comprueba que se ejecuta tras cerrar SSH/reiniciar el servicio.
  3. Comprueba la zona horaria efectiva del servicio y de la tarea.
  4. Define timeout, límite de peticiones y presupuesto API.
  5. No programes escrituras destructivas sin revisión explícita.

Documentación: https://github.com/HKUDS/nanobot/blob/main/docs/automations.md

10. Permisos y límites de aislamiento

El workspace y las restricciones de la aplicación no constituyen una frontera del kernel. bwrap y seatbelt tampoco aíslan la red. Para datos de usuarios independientes, separa cuentas, credenciales y entornos según el nivel de confianza.

Restringe la salida a servicios necesarios y bloquea el acceso a metadatos de nube y redes internas. Mantén tools.ssrfWhitelist vacía salvo excepciones justificadas. Un agente con lectura de secretos y salida de red puede exfiltrarlos incluso dentro de un contenedor.

Revisa scripts de skills y MCP, y trata mensajes, documentos y páginas externas como entradas no confiables. Conserva logs y cambios de archivos con una política de retención adecuada.

11. Operación, backup y recuperación

Observabilidad

nanobot --version
nanobot status
nanobot channels status
nanobot gateway status
nanobot gateway logs

# si usas systemd:
systemctl --user status nanobot-gateway
journalctl --user -u nanobot-gateway -n 100 --no-pager

# si usas Compose:
docker compose ps
docker compose logs --tail=100 nanobot-gateway

nanobot gateway status/logs corresponden al modo en background del propio CLI; con systemd o Compose conviene usar el supervisor real.

Backup seguro (propuesta operativa)

Con el servicio parado, guarda ~/.nanobot (incluye config, sesiones, workspace y, potencialmente, secretos). Ejemplo conceptual:

systemctl --user stop nanobot-gateway
umask 077
tar -czf "$HOME/nanobot-backup-$(date +%F).tar.gz" -C "$HOME" .nanobot
systemctl --user start nanobot-gateway

Cifra el TAR antes de transferirlo, restringe sus permisos y prueba la restauración en otro entorno. Respalda ~/.config/nanobot/secrets.env por separado: está fuera de la carpeta ~/.nanobot.

Actualización controlada

# Si se instaló con uv:
uv tool upgrade nanobot-ai
# Si se instaló con pipx:
pipx upgrade nanobot-ai
# Si usa virtualenv:
~/.venvs/nanobot/bin/python -m pip install -U nanobot-ai

Después compara nanobot --version, relee release notes, reinicia servicio, prueba Telegram, pruebas de pairing, sandbox y automations. Para git/Compose, fija commit, haz backup y reconstruye con docker compose build y up -d tras revisar cambios. No hagas actualizaciones de main desatendidas en producción.

Troubleshooting (orden de diagnóstico)

SíntomaQué comprobar primero
nanobot: command not foundPATH, venv, runner uv/pipx, instalación como usuario correcto
status OK pero no respondecredencial del proveedor, ID de modelo, endpoint, red saliente, cuotas
Telegram sin mensajeschannels status, token, plugin en el mismo venv, gateway vivo, conectividad
Recibo código pero no accesoaprobar pairing desde CLI/superficie autorizada
WebUI inaccesible por SSHservicio escuchando, ssh -L, puerto local ocupado, bind loopback
Herramientas no leen archivosworkspace seleccionado, permisos Unix, restrictToWorkspace, rutas sandbox
bwrap falla con Operation not permittednamespaces de usuario, política del host, seccomp/Compose override
automations no se ejecutanservicio persistente, zona horaria, logs, cron, permisos de tarea
sube consumo/tokenssesiones acumuladas, concurrencia, bucles de herramienta, modelo elegido

12. Validación del despliegue

  • Prueba respuesta CLI y Telegram, y rechazo de remitentes no autorizados.
  • Comprueba continuidad al cerrar SSH, exposición de puertos y permisos de herramientas.
  • Ejecuta una tarea programada de prueba; mide recursos, latencia y consumo API.
  • Restaura un backup y registra cuenta, rutas, supervisor y versión desplegada.

13. Referencias oficiales

  1. README del proyecto
  2. Instalación y Quick Start
  3. Deployment — Compose, Docker, systemd, LaunchAgent
  4. Configuration — modelos, secretos, tools, sandbox, MCP
  5. Conectar Telegram y pairing
  6. Automations
  7. Guía segura de agente local

Versiones (1)

VersiónDescargas (semana)Descargas (total)Publicación
0.1.0latest

Primera versión publicada.

0114 de octubre de 2026