Cómo instalar y configurar Agentbox (Guía Paso a Paso)

Agentbox es una plataforma de orquestación avanzada diseñada específicamente para desarrolladores que necesitan ejecutar múltiples agentes de IA (como Claude Code o Codex) en un entorno persistente y auto-alojado. A diferencia de las herramientas locales, Agentbox permite que los agentes trabajen continuamente en un servidor (VPS), permitiéndote monitorearlos desde cualquier dispositivo a través de terminales web interactivos.

En esta guía, detallaremos el proceso completo de instalación y configuración utilizando el método recomendado: Docker Compose. Este método garantiza que las redes, volúmenes y puertos se configuren correctamente para un entorno de producción listo para el uso diario.

Prerrequisitos del Sistema

Antes de iniciar la instalación, asegúrate de que tu servidor cumple con los siguientes requisitos mínimos para garantizar un rendimiento fluido:

• Sistema Operativo: Distribuciones Linux basadas en Debian o Ubuntu (recomendado 20.04+).
• Hardware: Mínimo 4GB de RAM (recomendado si planeas ejecutar múltiples agentes simultáneamente, ya que cada agente consume recursos de memoria y CPU).
• Software Base: Docker Engine y Docker Compose instalados en el sistema.
• Conectividad: Acceso a internet estable para que los agentes puedan comunicarse con las APIs de Anthropic (Claude), OpenAI o proveedores compatibles.

Paso 1: Preparación del Entorno y Docker

Primero, actualiza los repositorios de tu sistema y asegúrate de que las herramientas básicas estén disponibles. Si aún no tienes Docker instalado, sigue estos pasos:

# Actualizar el sistema e instalar dependencias base
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git

Si necesitas instalar Docker desde cero en un servidor limpio, se recomienda utilizar el script oficial de Docker para asegurar la última versión estable.

Paso 2: Clonación y Configuración de Variables

Clona el repositorio oficial de Agentbox. Es fundamental trabajar dentro del directorio clonado para que los archivos de configuración se mantengan vinculados correctamente.

# Clonar el repositorio
git clone https://github.com/jabezpauls/agentbox.git
cd agentbox

Configuración del archivo .env

Agentbox utiliza un archivo de entorno para gestionar las claves de API y la configuración interna. Debes crear una copia del ejemplo proporcionado:

# Crear el archivo de configuración basado en el ejemplo
pc .env.example .env

Edita el archivo con tu editor preferido (ej. nano o vim) para configurar tus credenciales:

nano .env

Importante: Asegúrate de rellenar los campos correspondientes a Anthropic (para Claude Code) u OpenAI. No compartas este archivo públicamente, ya que contiene tus llaves privadas.

Paso 3: Despliegue con Docker Compose

Utiliza Docker Compose para levantar el entorno completo. Este método es preferible porque gestiona automáticamente las redes internas y los volúmenes de persistencia.

# Levantar los contenedores en modo desatendido (detached)
docker compose up -d

Si realizas cambios en el archivo .env o modificas el docker-compose.yml, debes reconstruir las imágenes para que surtan efecto:

# Reconstruir y reiniciar tras cambios de configuración
docker compose up -d --build

Verificación y Diagnóstico

Una vez ejecutado el comando de despliegue, verifica que todos los servicios estén en estado running:

docker compose ps

Si algún contenedor falla o no inicia, puedes revisar los logs en tiempo real para identificar errores de configuración (como llaves API inválidas):

# Ver logs del contenedor principal
docker compose logs -f

Puedes acceder al panel de control a través del puerto especificado en el archivo docker-compose.yml (por defecto, revisa si es el 80 o un puerto personalizado).

Seguridad, Proxy Inverso y Buenas Prácticas

• Firewall: Si tu servidor tiene una IP pública, utiliza ufw para permitir solo los puertos necesarios.
• Proxy Inverso (Recomendado): Para un entorno de producción, se recomienda utilizar Nginx Proxy Manager o Caddy. Esto permite gestionar certificados SSL (Let's Encrypt) y ocultar el puerto interno del contenedor detrás de un dominio con HTTPS.
• Backups: Realiza copias periódicas del volumen mapeado en Docker donde se guardan los proyectos y estados de los agentes para evitar pérdida de datos ante fallos de disco o errores de configuración.

Preguntas Frecuentes (FAQ)

Recursos Relacionados:

• Ficha oficial de Agentbox
• Alternativas a Agentbox