Cómo autoalojar Orca en un VPS: guía paso a paso

En resumen. Orca (stablyai/orca) es un entorno de desarrollo agéntico (ADE) de código abierto que corre agentes de codificación en paralelo, cada uno en su propio git worktree, desde una sola interfaz. Puedes autoalojar Orca en un Ubuntu sin interfaz gráfica en menos de 20 minutos usando el AppImage oficial y orca serve. El punto de entrada práctico para un fleet de dos o tres agentes es el Core VPS 6 (6 vCPU, 12 GB RAM). Para cuatro agentes o más corriendo en paralelo, pásate al Core VPS 8 (8 vCPU, 24 GB RAM).

Orca es un runtime de agentes de IA autoalojado desarrollado por stablyai. Córrelo en un VPS y obtienes sesiones de agentes persistentes, sin costo de cómputo local, y un entorno del lado del servidor al que tu desktop o celular se conectan desde cualquier lugar.

Requisitos previos

Correr el entorno de desarrollo agéntico Orca como runtime autoalojado requiere un VPS con suficiente RAM y un entorno Linux compatible con modo sin interfaz gráfica. Asegúrate de tener:

• Un Core VPS 6 de Contabo o superior (en el Paso 1 encontrarás la guía de dimensionamiento). Los comandos de abajo están probados en Ubuntu 22.04 LTS. Si usas Ubuntu 24.04 LTS, revisa el aviso en el Paso 2 sobre los nombres de paquetes que difieren.
• Acceso root al servidor por SSH.
• Al menos una suscripción de agente que vayas a traer a Orca, como Claude Code, Codex u OpenCode. Orca no incluye un agente propio ni te cobra por uno.
• Un dominio si quieres acceso HTTPS a través de un reverse proxy (opcional, pero recomendado para cualquier cosa más allá de una prueba local).

Orca no tiene sistema de cuentas ni login. Las suscripciones de agente que ya tienes son las credenciales que usa.

Paso 1: Aprovisiona tu VPS de Contabo

Los requisitos de recursos de Orca crecen con el número de agentes que planeas correr en paralelo. Cada agente mantiene un git worktree abierto y corre una sesión de terminal con un proceso activo de Claude Code o Codex. Una regla práctica de planeación: presupuesta aproximadamente 4 GB de RAM por agente en paralelo, más 4 GB de base para el SO, Xvfb y el propio runtime de Orca.

Para la ADE de Orca en un VPS, estos planes de Contabo cubren los casos de uso más comunes:

Para aprovisionar tu servidor:

• Ve a contabo.com y selecciona el plan Cloud VPS que se ajuste a tu carga de trabajo.
• Elige Ubuntu 22.04 LTS como sistema operativo.
• Selecciona un datacenter cercano a tu equipo. Los datacenters de la UE (Alemania, Países Bajos) mantienen tu código y tus prompts en infraestructura europea.
• Completa el pedido. Tu servidor suele estar disponible en cuestión de minutos.
• Conéctate por SSH: ssh root@<ip-de-tu-servidor>

Paso 2: Instala el runtime de Orca

Orca se distribuye como un AppImage de Linux autocontenido. Para configurarlo como runtime de agentes de IA autoalojado en un VPS sin interfaz gráfica necesitas libfuse2 (requerido por AppImage), xvfb-run (el wrapper que inicia un display virtual por cada comando) y un conjunto de bibliotecas de runtime de GTK y Electron que una imagen mínima de servidor Ubuntu no incluye por defecto.

Instala todas las dependencias y luego descarga el AppImage:

sudo apt-get update

sudo apt-get install -y \
  curl libfuse2 xvfb \
  libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 \
  libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 \
  libpango-1.0-0 libcairo2 libgtk-3-0 libgdk-pixbuf2.0-0 \
  libnss3 libnspr4 libxss1 libxtst6 libasound2t64

sudo mkdir -p /opt/orca

sudo curl -L https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage \
  -o /opt/orca/orca-linux.AppImage

sudo chmod +x /opt/orca/orca-linux.AppImage

Usuarios de Ubuntu 24.04: libfuse2 pasó a llamarse libfuse2t64 y libasound2 pasó a libasound2t64 en la versión 24.04. El comando de arriba ya usa los nombres de 24.04. En Ubuntu 22.04, reemplaza libfuse2t64 por libfuse2 y libasound2t64 por libasound2.

Verifica que el binario sea ejecutable antes de continuar:

/opt/orca/orca-linux.AppImage --version

Deberías ver un string con la versión de Orca. Si recibes el error libfuse.so.2: cannot open shared object file, comprueba que el paquete libfuse correcto para tu versión de Ubuntu esté instalado. Si ves libatk-1.0.so.0: cannot open shared object file, vuelve a ejecutar el bloque completo de apt-get install de arriba.

Paso 3: Crea el usuario del servicio y ejecuta una prueba en primer plano

Crea el usuario de servicio no-root dedicado antes de correr cualquier prueba. Electron rechaza iniciarse como root sin --no-sandbox, y el usuario de servicio necesita ser dueño del directorio de Orca antes de que la unidad de systemd lo ejecute:

sudo useradd --system --create-home --shell /usr/sbin/nologin orca
sudo chown -R orca:orca /opt/orca

Ahora corre orca serve en primer plano como el usuario orca para confirmar que el runtime inicia correctamente y obtener la URL de emparejamiento. El wrapper xvfb-run inicia un display virtual automáticamente. Orca no inicia Xvfb por sí solo en un VPS sin interfaz gráfica:

sudo -u orca sh -c 'xvfb-run --auto-servernum \
  LIBGL_ALWAYS_SOFTWARE=1 \
  /opt/orca/orca-linux.AppImage serve --port 6768'

La terminal imprime un endpoint del runtime y una URL de emparejamiento. Abre esa URL en tu app de Orca para desktop (Archivo > Conectar a remoto) o escanéala con la app móvil de Orca para vincular tu sesión local con el runtime del VPS. Detén el proceso en primer plano con Ctrl+C una vez que confirmes que la conexión funciona.

Si los clientes van a llegar al servidor por una red privada o Tailscale, agrega --pairing-address con la dirección que deben usar:

sudo -u orca sh -c 'xvfb-run --auto-servernum \
  LIBGL_ALWAYS_SOFTWARE=1 \
  /opt/orca/orca-linux.AppImage serve --port 6768 --pairing-address 100.64.1.20'

Reemplaza 100.64.1.20 con la IP LAN, la IP de Tailscale o el hostname público de tu servidor.

Paso 4: Inicia el runtime del agente como servicio persistente

Correr orca serve como servicio de systemd mantiene tu runtime de agentes de IA autoalojado activo a través de desconexiones de SSH y reinicios. El usuario de servicio ya fue creado en el Paso 3. Escribe la unidad de servicio:

sudo tee /etc/systemd/system/orca-serve.service > /dev/null << 'EOF'
[Unit]
Description=Orca runtime server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=orca
WorkingDirectory=/home/orca
Environment=LIBGL_ALWAYS_SOFTWARE=1
ExecStart=/usr/bin/xvfb-run --auto-servernum /opt/orca/orca-linux.AppImage serve --port 6768 --pairing-address YOUR_SERVER_IP
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

xvfb-run --auto-servernum inicia un display virtual y establece DISPLAY automáticamente. No agregues una línea con DISPLAY= como variable de entorno; las dos entrarían en conflicto. Reemplaza YOUR_SERVER_IP con la dirección que usarán los clientes. Activa e inicia el servicio:

sudo systemctl daemon-reload
sudo systemctl enable --now orca-serve.service
sudo journalctl -u orca-serve.service -f

El output del journal debe mostrar el endpoint del runtime y la URL de emparejamiento. Si el servicio falla de inmediato, revisa el mensaje de error en el journal. La sección de Solución de problemas más abajo cubre los casos más comunes.

Paso 5: Configura tu fleet de agentes

Con orca serve corriendo, conecta tu app de Orca para desktop al VPS:

• Abre Orca en tu desktop o laptop.
• Ve a Archivo > Conectar a remoto e ingresa la URL de emparejamiento del output del journal, o escanéala con la app móvil de Orca.
• Una vez conectado, crea un nuevo worktree: haz clic en New Worktree, selecciona un repositorio y elige un agente (Claude Code, Codex u otro agente CLI compatible).
• El proceso del agente corre en el VPS dentro de ese worktree. Tu app de desktop es la interfaz. Todo el cómputo ocurre en el servidor.
• Para correr agentes en paralelo, crea worktrees adicionales en el mismo repositorio o en otros distintos. Cada uno obtiene su propio git worktree aislado y su propia sesión de terminal.

La app móvil companion de Orca (iOS y Android) te permite monitorear el estado de los agentes y enviar prompts de seguimiento desde tu celular, mientras la ADE de Orca hace el trabajo real en el VPS.

Opcional: Configura un reverse proxy

Por defecto, orca serve escucha en el puerto 6768 sin TLS. Exponer un runtime de agentes de IA autoalojado en una IP pública sin TLS no es buena idea. Pon Nginx delante y obtén un certificado con Certbot:

sudo apt-get install -y nginx certbot python3-certbot-nginx

Crea la configuración del sitio:

sudo tee /etc/nginx/sites-available/orca << 'EOF'
server {
    listen 80;
    server_name orca.tudominio.com;

    location / {
        proxy_pass http://127.0.0.1:6768;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/orca /etc/nginx/sites-enabled/
sudo nginx -t &amp;& sudo systemctl reload nginx
sudo certbot --nginx -d orca.tudominio.com

Después de que Certbot termine, tu runtime de Orca es accesible en https://orca.tudominio.com con un certificado TLS válido. Actualiza la dirección de emparejamiento en la unidad de servicio de systemd para que coincida con el dominio.

Solución de problemas: casos comunes

Si tu runtime de agentes de IA autoalojado o la ADE de Orca no inicia, o los agentes no logran conectarse, revisa estas causas frecuentes:

• dlopen(): error loading libfuse.so.2: El paquete libfuse correcto para tu versión de Ubuntu no está instalado. En Ubuntu 22.04: sudo apt-get install -y libfuse2. En Ubuntu 24.04: sudo apt-get install -y libfuse2t64.
• Missing X server or $DISPLAY: Orca no inicia Xvfb automáticamente en un VPS sin interfaz gráfica. Usa xvfb-run --auto-servernum como se muestra en los Pasos 3 y 4. Si xvfb-run no está instalado, instálalo con sudo apt-get install -y xvfb.
• libatk-1.0.so.0: cannot open shared object file (o cualquier error similar de biblioteca GTK/Electron): El conjunto completo de dependencias de runtime de GTK y Electron del Paso 2 no se instaló. Vuelve a ejecutar el bloque completo de apt-get install del Paso 2.
• Out of memory / el agente se cae a mitad de una tarea: El RAM de tu plan es insuficiente para el número de agentes en paralelo. Revisa la memoria libre con free -h mientras los agentes están corriendo. Pásate al Core VPS 8 o superior si los 12 GB están consistentemente llenos.
• Conflicto de puerto en 6768: Otro proceso está usando el puerto. Ejecuta sudo ss -tlnp | grep 6768 para identificarlo, o cambia el flag --port en la unidad de servicio a un puerto libre.
• Errores de API key de un agente: Orca pasa tus credenciales de agente existentes. Vuelve a autenticarte con el CLI del agente directamente en el VPS (por ejemplo, claude auth login) mientras tienes una sesión SSH como el usuario de servicio orca: sudo -u orca claude auth login.
• Los clientes no pueden conectarse: Confirma que el puerto 6768 está abierto en el firewall de Contabo (o en ufw a nivel de OS) y que --pairing-address coincide con la dirección que los clientes intentan usar.

Preguntas frecuentes: autoalojar Orca