Cómo desplegar agency-orchestrator en un VPS: flujos de agentes de IA autoalojados

En resumen. agency-agents es una biblioteca de personas de IA especializadas y agency-orchestrator es el framework que las ejecuta como un servidor de agentes autoalojado y siempre disponible. Una sola frase, o un flujo en YAML, pone a varios expertos de IA a trabajar en paralelo sobre un mismo entregable. Esta guía instala agency-orchestrator con Docker en un VPS de Contabo, accesible desde cualquier dispositivo. Calcula unos 25 minutos en un Cloud VPS 8.

Qué es agency-orchestrator y cómo se relaciona con agency-agents

agency-orchestrator es el framework de agentes de IA que convierte la biblioteca de personas agency-agents en un servidor multiagente permanente que puedes ejecutar en un VPS. Los dos proyectos se confunden con frecuencia, así que conviene separarlos antes de desplegar nada.

agency-agents, creado por msitarzewski y con licencia MIT, es una biblioteca de 184 archivos de personas de IA especializadas en inglés, con más de 129,000 estrellas en GitHub al momento de escribir esto. Cada persona es una instrucción en markdown que instalas en Claude Code, Cursor, GitHub Copilot o una herramienta de programación similar. Aquí no hay componente de servidor ni nada que desplegar: agency-agents vive por completo dentro de tu asistente de programación local.

agency-orchestrator, creado por jnMetaCode y con licencia Apache-2.0, es un proyecto aparte que usa esas mismas personas de agency-agents como sus roles de IA, junto con una biblioteca de personas en chino que mantiene por su cuenta. Añade un motor de flujos en YAML, ejecución paralela mediante un DAG, soporte para 10 proveedores de LLM y una interfaz web llamada Studio, y entrega todo eso como imagen de Docker. Siendo un agente de IA de código abierto, agency-orchestrator es lo que corre en el VPS y lo que instala esta guía.

Ejecutarlo en un VPS en lugar de una laptop cambia cuatro cosas: tus flujos quedan siempre activos, se pueden disparar por API o por llamadas MCP desde una pipeline de CI/CD, sus resultados se guardan siempre en el mismo lugar y todo el montaje queda accesible desde cualquier dispositivo de la red.

Requisitos

Para correrlo como agente de IA autoalojado necesitas un VPS, Docker y acceso a uno de los diez proveedores de LLM compatibles.

• Contabo Cloud VPS 8 (8 vCPU Cores, 24 GB RAM, 300 GB SSD) para flujos con mucha ejecución en paralelo y proveedores basados en API, o Cloud VPS 4 (4 vCPU Cores, 8 GB RAM) para flujos más ligeros con proveedores sin llave como Claude Code o Gemini CLI
• Contabo Cloud VDS S (6 vCores dedicados, AMD EPYC 7282, 24 GB RAM, 180 GB NVMe) si planeas correr inferencia local con Ollama y modelos de 13B parámetros o más
• Docker Engine y el plugin de Docker Compose
• Un dominio y Caddy para HTTPS (opcional, recomendado para el Web Studio)
• Un método de acceso a LLM: una llave de API de Anthropic, DeepSeek u OpenAI, o una suscripción vigente a Claude Pro/Max, Gemini o GitHub Copilot para el acceso sin llave

Paso 1: Aprovisiona y asegura tu VPS

Este paso te deja un servidor Ubuntu endurecido y listo para ejecutar tu agente de IA autoalojado bajo Docker.

1. Crea un Contabo Cloud VPS 8, elige tu región y selecciona Ubuntu 24.04 LTS.
2. Conéctate por SSH como root: ssh root@<your-ip>
3. Crea un usuario sin privilegios de root: adduser ao && usermod -aG sudo ao
4. Configura la autenticación con llaves SSH y desactiva el acceso por contraseña.
5. Configura UFW para permitir SSH (22), HTTP (80), HTTPS (443) y el puerto del Studio (8088, restringido a tu IP o detrás de Caddy).
6. Activa el firewall: ufw enable

Paso 2: Instala Docker y Docker Compose

agency-orchestrator se distribuye como imagen de Docker, así que la instalación empieza con Docker Engine y el plugin de Compose.

apt update && apt install -y ca-certificates curl gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update && apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
systemctl enable --now docker
usermod -aG docker ao

Comprueba la instalación:

docker run hello-world

Paso 3: Despliega agency-orchestrator con Docker

Hay dos caminos para poner agency-orchestrator, y las personas de agency-agents que ejecuta, en tu VPS: un solo comando docker run para una prueba rápida, o Docker Compose para un despliegue que piensas conservar.

Inicio rápido:

docker run -d \
  --name agency-orchestrator \
  --restart unless-stopped \
  -p 8088:8088 \
  -v ao-data:/data \
  ghcr.io/jnmetacode/agency-orchestrator:latest

Docker Compose (recomendado para producción, porque incluye los volúmenes para las salidas y la configuración persistente):

git clone https://github.com/jnMetaCode/agency-orchestrator.git
cd agency-orchestrator
docker compose up -d

Verifica con curl http://localhost:8088, que debe devolverte el HTML del Web Studio. La etiqueta de la imagen, el puerto y las variables de entorno de proveedor (DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, AO_DATA_DIR) que aparecen arriba están contrastadas con la documentación vigente.

Paso 4: Configura tu proveedor de LLM y las llaves de API

agency-orchestrator llega a sus personas de agency-agents por uno de dos modos: una llave de API o un proxy de CLI sin llave. Lo que elijas define qué tan confiable resulta dejar el agente autoalojado corriendo sin supervisión.

La opción A, proveedores con llave de API, es la elección práctica para un VPS sin pantalla. DeepSeek es la opción económica por defecto. Anthropic y OpenAI funcionan igual.

# In docker run or docker-compose.yml
DEEPSEEK_API_KEY=your_key_here
# Or for Anthropic
ANTHROPIC_API_KEY=your_key_here

La opción B, proveedores sin llave como Claude Code o Gemini CLI, enruta las peticiones a través de una suscripción vigente. Necesitan una sesión de autenticación interactiva, sencilla en una máquina local pero incómoda de mantener en un VPS sin pantalla. Para un despliegue permanente, un proveedor con llave de API resulta más confiable.

En ambos casos, las llaves se capturan una sola vez en la página Providers del Web Studio y quedan guardadas en el volumen montado, así que sobreviven a los reinicios del contenedor.

Paso 5: Publica el Web Studio con Caddy y HTTPS

Poner el Web Studio detrás de Caddy le da a tu agente de IA autoalojado un dominio real, HTTPS y protección con contraseña por basic auth en unos pocos pasos.

ao.yourdomain.com {
    reverse_proxy localhost:8088
    basicauth /* {
        # Generate with: caddy hash-password
        admin $2a$14$...
    }
}

1. Instala Caddy: apt install -y caddy
2. Guarda el Caddyfile de arriba en /etc/caddy/Caddyfile.
3. Recarga Caddy: systemctl reload caddy
4. Entra a https://ao.yourdomain.com. El Studio debe cargar por HTTPS.

El Studio guarda tus llaves de API de LLM, así que protégelo con basic auth o limita el acceso a una VPN o a un rango de IP conocido.

Paso 6: Ejecuta tu primer flujo multiagente

Como framework de agentes de IA, agency-orchestrator acepta un flujo desde el Web Studio, desde la CLI o mediante una conexión MCP con un agente de programación como Claude Code o Cursor. Las tres vías disparan el mismo reparto de personas.

Desde el Web Studio, sin escribir código:

1. Abre https://ao.yourdomain.com.
2. Escribe una instrucción de una frase, por ejemplo “Analiza la viabilidad de una herramienta SaaS de facturación para freelancers.”
3. Haz clic en Run. agency-orchestrator elige los roles automáticamente y ejecuta un flujo en DAG.
4. Consulta la pestaña Outputs para ver los resultados.

Desde la CLI, dentro del contenedor:

docker exec -it agency-orchestrator npx ao compose \
  "PR code review covering security and performance" \
  --run

Con MCP, el patrón documentado oficialmente conecta Claude Code o Cursor con una instancia ao serve que corre en la misma máquina:

{
    "mcpServers": {
      "agency-orchestrator": {
        "command": "npx",
        "args": ["agency-orchestrator", "serve"]
      }
    }
}

Paso 7: Conserva las salidas y automatiza los respaldos

Tu agente de IA autoalojado escribe cada resultado en ao-output/, dentro del volumen de Docker montado en /data, y un respaldo diario mantiene esos datos a salvo fuera del VPS.

docker exec agency-orchestrator tar czf - /data/ao-output | \
  s3cmd put - s3://your-bucket/ao-backup-$(date +%Y%m%d).tar.gz

Prográmalo como tarea cron en el host del VPS:

0 2 * * * /path/to/backup-script.sh

Solución de problemas frecuentes en el despliegue

Casi todos los problemas con agency-orchestrator se reducen a tres causas.

El contenedor arranca y se apaga de inmediato. Revisa primero docker logs agency-orchestrator. Lo más común es que falte una variable de entorno con la llave de API o que el nombre esté mal escrito, así que confirma que coincida con los nombres del Paso 3.

El Web Studio no responde en tu dominio. Confirma que UFW permita los puertos 80 y 443, que Caddy se haya recargado sin errores (systemctl status caddy) y que la línea reverse_proxy del Caddyfile apunte a localhost:8088.

Un proveedor sin llave falla con un error de autenticación. En un VPS sin pantalla es lo esperado. Cambia a un proveedor con llave de API (Paso 4) en lugar de pelearte con una sesión de CLI interactiva sin display.

Preguntas frecuentes: agency-orchestrator en un VPS