Instalación y self-host

Olivares AI se distribuye como un único binario estático con la consola web embebida. El control plane — la parte que observa, gobierna y audita los agentes de IA en tu infraestructura — se ejecuta en tu perímetro y puede funcionar air-gapped. Esta página cubre la instalación con forma de producción: un host, valores por defecto seguros, sondas de salud y la elección de almacén que importa en despliegues multi-tenant.

Si de momento solo quieres echar un vistazo, el quickstart arranca un parque sintético de demostración en unos cinco minutos. Esta página es la postura real.

Obtener el binario

No hay una URL pública de descarga que copiar aquí. Obtienes el binario controlplane de una de dos maneras:

• Un artefacto de release firmado — verifícalo antes de ejecutarlo. Consulta verificar una release para la cadena de firma y procedencia.
• Compilar desde el código fuente — el almacén es SQLite en Go puro, así que no hay toolchain de C. Un task build produce ./bin/controlplane con la interfaz web y los conectores de primera parte embebidos; controlplane version confirma lo que has compilado.

En cualquier caso acabas con un único fichero. Instálalo y crea un usuario de servicio dedicado en lugar de ejecutarlo como root.

Valores por defecto seguros

Los valores por defecto están elegidos para que una instalación nueva sea segura antes de tocar ningún flag.

Un primer arranque mínimo:

controlplane serve \
  --listen 127.0.0.1:8443 \
  --grpc-listen 127.0.0.1:8444 \
  --data-dir /var/lib/olivares

El directorio de datos contiene el almacén, la clave de firma de auditoría y el material TLS. Haz copia de seguridad de él y protégelo con permisos restrictivos.

Reclamar el token de configuración de un solo uso

Una instalación nueva no tiene credenciales por defecto. En el primer arranque, mientras no existe ningún usuario, el motor acuña un token de configuración de un solo uso y lo imprime únicamente en stdout — nunca en los logs:

=== FIRST-BOOT SETUP ===
No users exist yet. Create the first administrator:
  POST /v1/setup  {"token":"olst_…","email":"you@example.com","password":"..."}
This token is shown ONCE and is single-use.
========================

Solo se almacena el hash del token, así que un token que se pierda no se puede recuperar y un reinicio no lo vuelve a imprimir. En una instalación recién creada que aún no tiene usuarios, eliminar el token almacenado del directorio de datos y reiniciar acuña uno nuevo. Esa recuperación solo funciona mientras no existe ningún usuario, de modo que nunca puede tomar el control de una instalación ya configurada.

Después de crear el primer administrador, el endpoint de configuración queda cerrado de forma definitiva.

Sondas de salud

El listener HTTP expone dos sondas con semánticas deliberadamente distintas. Conéctalas a la sonda de Kubernetes que corresponda — confundir las dos provoca bucles de reinicio o enrutado obsoleto.

/livez es liveness. No ejecuta ninguna comprobación de dependencias: si el proceso puede responder, está vivo. Una dependencia que falle nunca debe disparar un reinicio por liveness.

curl -ks https://127.0.0.1:8443/livez
# {"status":"ok"}

/readyz es readiness, y es la señal de disponibilidad que un balanceador de carga debería usar para drenar. Devuelve 503 en dos casos, distinguidos en el cuerpo para tus logs:

• Almacén inalcanzable — {"status":"unavailable","store":"down"}. El ping al almacén se ejecuta con un timeout corto, de modo que un backend atascado drena la instancia en lugar de quedarse colgado.
• No es el escritor activo — {"status":"standby","store":"up","leader":false}. En un clúster activo-pasivo un standby reporta 503 aquí para que el Service deje de enrutar hacia él, sin reiniciarlo (eso es trabajo de /livez — un hot standby debe permanecer activo para tomar el relevo). Cuando el líder muere, un standby adquiere el liderazgo y esto cambia a 200, de modo que el tráfico sigue al nuevo líder automáticamente.

Cuando el motor está listo devuelve 200:

{"status":"ok","store":"up","leader":true,"setup_required":false}

setup_required se reporta para observabilidad pero no hace fallar el readiness — un motor recién arrancado está listo para ser configurado. En un almacén de un solo nodo el escritor está siempre activo, así que /readyz simplemente sigue la accesibilidad del almacén.

Elegir un almacén

El almacén se selecciona con --engine. Elige por topología, no por preferencia.

SQLite (por defecto)

El almacén SQLite embebido en Go puro no necesita nada externo y es la elección correcta para un único nodo, un laboratorio, un parque pequeño o una instalación air-gapped. Todo el estado vive en el directorio de datos.

Postgres (multi-tenant)

Para despliegues multi-host o multi-tenant, usa Postgres. No te conectes como superusuario ni como un rol con BYPASSRLS. El aislamiento entre tenants se impone mediante FORCE ROW LEVEL SECURITY, y Postgres salta silenciosamente toda la seguridad a nivel de fila para esos roles — lo que dejaría únicamente el predicado de la capa de aplicación entre tenants. El motor se niega a arrancar contra un rol privilegiado a menos que pases explícitamente --allow-privileged-db-role (solo single-tenant o desarrollo).

Aprovisiona en su lugar un rol dedicado con privilegios mínimos — NOSUPERUSER NOBYPASSRLS NOCREATEROLE NOCREATEDB. Es propietario de su propia base de datos, así que puede aplicar migraciones de esquema; FORCE ROW LEVEL SECURITY aplica la política de tenant incluso al propietario de la tabla, de modo que un rol propietario-pero-que-no-salta permanece totalmente aislado.

controlplane serve --engine postgres \
  --dsn "postgres://olivares_app:$DB_PASSWORD@db:5432/olivares?sslmode=verify-full" \
  --data-dir /var/lib/olivares

Usa sslmode=verify-full y una contraseña SCRAM fuerte. Las lecturas System genuinamente cross-tenant (la lista de organizaciones, la cobertura de checkpoints multi-tenant) necesitan un rol aparte: aprovisiona uno que sea NOSUPERUSER BYPASSRLS — privilegio mínimo pero capaz de leer entre tenants — y apunta --admin-dsn a él. Omítelo en los despliegues single-tenant y esas lecturas quedan simplemente limitadas por RLS.

Antes de darlo por terminado

Dos cosas deciden si tu evidencia sobrevive a un incidente:

• Haz copia de seguridad de la clave de firma de auditoría fuera del host. Firma el ledger de auditoría append-only; si se pierde, el ledger ya no se puede volver a verificar. El motor avisa en el primer arranque — no hay escrow impuesto.
• Mantén una copia fuera del host de la clave pública del ledger. Esa copia fuera del host es lo que hace que la verificación de auditoría sea resistente tras un compromiso del host.

Después programa copias de seguridad reales del directorio de datos.

Qué se ejecuta dónde

Solo el control plane es tuyo para ubicarlo — air-gapped si lo eliges. Los colectores (data plane) siempre se ejecutan en tu infraestructura. Un matiz que conviene dejar claro sin rodeos: Olivares gobierna y audita el uso de Claude, pero la propia inferencia de Claude no está self-hosted — llega a la API de Anthropic (directamente o vía Bedrock, Vertex o Foundry). Solo los modelos genuinamente self-hosted se ejecutan offline. Consulta la página de honestidad y límites para conocer la frontera completa.

Próximos pasos

• Conecta señal real: conectar una fuente y conectar Claude Code.
• Ajusta la instalación: la referencia de configuración.
• Entiende el modelo: el mapa de acceso de lectura/escritura.