Instalar Cordane — Hub para Agentes de IA Autoalojable | Guía Verificada

Instalar Cordane — Hub para Agentes de IA Autoalojable

Última actualización: 2026-10-05 | Fuentes verificadas: GitHub cordane/cordane | Documentación oficial

/software/cordane — Ficha de software en HostingByte

¿Qué es Cordane?

Cordane es una plataforma de control centralizado para gestionar equipos de desarrollo y agentes de inteligencia artificial (Claude Code, Codex, Opencode) ejecutándose en hardware propio. Utiliza arquitectura outbound: los workers establecen conexiones WebSocket hacia el hub sin puertos entrantes ni VPN.

┌─────────────────────────────────────────────────────────────┐
│                    HUB (Control Plane)                       │
│              Interfaz web en navegador                       │
│         Autoalojado o Cloud Gestionado                       │
└─────────────────────────────────────────────────────────────┘
                              ↕ WebSocket outbound
┌─────────────────────────────────────────────────────────────┐
│                   WORKERS (Data Plane)                       │
│  Agentes, servidores de desarrollo y código                  │
│              En tus máquinas propias                         │
└─────────────────────────────────────────────────────────────┘

Prerrequisitos

Hub (Autoalojado — Community Tier Gratuito)

Requisito	Especificación
Sistema	Linux con Docker o binario Go estático único
CPU/RAM	~1 vCPU, 512 MB–1 GB RAM
Disk	Varios GB (SQLite + worktrees de Git)
Red	Puertos 80/443 abiertos para HTTPS automático
DNS	A record para hostname + wildcard *. para subdominios de preview
Requisito adicional	App de GitHub OAuth con callback URL configurada

Worker (cada máquina donde ejecutarán agentes)

Requisito	Especificación
Sistema	Linux o macOS
Requerido	Git (Cordane crea worktrees por ticket)
Opcional	Docker para agentes en contenedores sandboxeados
Capacidad	CPU/RAM/disk suficientes para builds y ejecuciones de agentes

Instalación Paso a Paso

1. Clonar Repositorio del Hub

git clone https://github.com/cordane/cordane.git
cd cordane/deploy

2. Configurar Variables de Entorno

cp .env.example .env

Variables clave a configurar en .env:

# URL pública del hub (incluye protocolo y dominio)
EXTERNAL_URL=https://tu-hub.ejemplo.com

# Hostname interno para el hub
CONTROL_HOST=tu-hub.ejemplo.com

# Clave secreta del hub (generar con openssl)
CORDANE_SECRET_KEY=$(openssl rand -base64 32)

# Credenciales GitHub OAuth (ver sección siguiente)
CORDANE_GITHUB_CLIENT_ID=...
CORDANE_GITHUB_CLIENT_SECRET=...

Generar CORDANE_SECRET_KEY:

openssl rand -base64 32

3. Configurar GitHub OAuth

Crear App OAuth en GitHub:

Ve a GitHub Settings → Developer settings → OAuth Apps
Click en New OAuth App
Rellena:

Application name: Cordane Hub Self-Hosted
Homepage URL: https://tu-hub.ejemplo.com
Authorization callback URL: https://tu-hub.ejemplo.com/api/v1/auth/github/callback

Click en Register application
Copia Client ID y Client secret

4. Iniciar con Docker Compose

docker compose up -d
docker compose logs -f cordane

5. Acceder al Hub

Abre tu navegador en EXTERNAL_URL y autentícate con GitHub. El primer usuario que se autentifica es admin.

Conectar un Worker

1. Obtener Token de Join desde el Hub

En la interfaz web del hub:

Ve a Workers → Add worker
Copia el comando de join (contiene token crdjt_...)

2. Instalar Worker en Máquina Objetivo

# En tu máquina worker
curl -fsSL https://tu-hub.ejemplo.com/install.sh | sh

3. Unir al Hub

cordane worker join https://tu-hub.ejemplo.com --token crdjt_...

Para reinicios (opcional):

cordane worker run

En unos segundos el worker aparecerá Online en el tablero.

Comprobación Posterior

Verificar Worker Online

# En el hub, abre Workers y confirma que aparece "Online"

Verificar Puertos (debería estar vacío — arquitectura outbound)

ss -ltnp
# No debería mostrar nada escuchando en puertos entrantes

Verificar Logs del Hub

docker compose logs -f cordane

Backup de SQLite

El hub utiliza SQLite para el estado. Backups sencillos vía Litestream hacia buckets S3 compatibles.

Configurar backup a S3

Edita .env:

CORDANE_LITESTREAM_S3_BUCKET=tu-bucket
CORDANE_LITESTREAM_S3_REGION=us-east-1
CORDANE_LITESTREAM_S3_ACCESS_KEY_ID=tu-access-key
CORDANE_LITESTREAM_S3_SECRET_ACCESS_KEY=tu-secret-key
CORDANE_LITESTREAM_S3_ENDPOINT=https://tu-s3-endpoint.com

Ejecutar backup manual

docker compose exec cordane litestream migrate
docker compose exec cordane litestream snapshot /tmp/snapshot.db

Actualización y Rollback

Actualizar Worker

# Descargar y aplicar actualización
cordane worker upgrade

# Solo verificar si hay actualización disponible
cordane worker upgrade --check

Actualizar Hub Self-Hosted

docker compose pull && docker compose up -d

Verificar versión en hub: Settings → Version (banner "update available" cuando haya nueva release)

Rollback (si es necesario)

# Detener y restaurar desde backup anterior
docker compose down
# Restaurar backup de SQLite manualmente o desde S3
docker compose up -d

Errores Habituales

Error	Causa	Solución
`401 Unauthorized` en OAuth	Callback URL incorrecto en GitHub App	Verificar que `https://tu-hub.ejemplo.com/api/v1/auth/github/callback` coincide exactamente
Worker no aparece "Online"	Token de join expirado o mal copiado	Generar nuevo token desde hub → Workers → Add worker
HTTPS no funciona	DNS en grey-cloud (Cloudflare)	Configurar DNS-only / DNS grey-cloud; Caddy termina TLS
`cordane: command not found`	Worker binario no instalado	Ejecutar `curl -fsSL https://tu-hub/install.sh \| sh`
Subdominios de preview no resuelven	Falta wildcard DNS `*.ejemplo.com`	Configurar A record wildcard en DNS provider

Seguridad

Cifrado AES-256-GCM: Secrets de aplicación y perfil cifrados en la base de datos con clave que el usuario controla — nunca almacenados en texto plano junto a los datos.
Sin Phone-home: El hub verifica su licencia offline con token firmado. Funciona incluso cuando los servidores de SHB no están disponibles.
Datos en tu perímetro: En modo cloud gestionado, agentes, fuente y secretos ejecutan solo en workers propios. El plano de datos nunca toca servidores de terceros.
Autenticación OAuth GitHub: Sin contraseñas. Primer usuario que se autentifica es admin.
Subdominios autenticados: Previews de aplicaciones con autenticación por defecto y escopado por equipo.

FAQ Basada en Evidencia

¿Qué máquinas pueden ejecutar un worker?

Cualquier sistema Linux o macOS que pueda ejecutar un binario Go. Desde laptop hasta VPS barato ($4-5/mo). Los workers son ligeros y escalables.

¿Cuántos agentes soporta?

Community tier: hasta 3 ejecuciones concurrentes de agente. Tier con licencia: ilimitado. Cada ticket obtiene su propio worktree y puertos.

¿Puedo cambiar entre autoalojado y cloud?

Sí. El único cambio es quién ejecuta el hub (control plane). Workers permanecen en tus máquinas. Puedes mover datos SQLite entre modos sin pérdida.

¿Tengo lock-in con Cordane?

No. Datos son SQLite plano exportable. Hub verifica licencia offline. Puedes migrar entre autoalojado y cloud gestionado libremente.

¿Qué agentes soporta?

Cualquier CLI agent: Claude Code, Codex, Aider o scripts propios. No estás lockeado a un modelo o proveedor específico.

¿Puedo usar tmux nativo?

No directamente — Cordane no soporta keybindings nativos de tmux. Usa terminales persistentes con PTY real que mapean sesiones tmux a espacios del tablero.

Precios

Tier	Precio	Características
Community (Gratuito)	$0/mo	1 worker, 1 proyecto, 2 usuarios, 3 concurrentes. Sin licencia, sin phone-home.
Self-hosted con Licencia	$19/user/mo	Ilimitado en workers, proyectos y concurrencia.
Cloud Gestionado	$39/mo + 3 seats	Hub ejecutado por SHB con TLS, backups y upgrades automáticos.

Enlaces Internos Contextuales

Documentación oficial
/software/cordane — Ficha de software en HostingByte
Alternativas y comparativas
Guías de HostingByte