Configurazione

La vera superficie di configurazione del piano di controllo Olivares AI — backend del datastore, TLS, sorgenti, chiave di firma dell'audit e multi-tenancy.

Il piano di controllo e un singolo binario Go, olivares, configurato da un piccolo insieme di flag sul suo sottocomando serve e da alcune variabili d’ambiente — non un file di configurazione sterminato. I default sono scelti per fallire chiusi: bind loopback, TLS attivo, nessuna credenziale distribuita. Tutto quanto segue e preso dalle definizioni dei comandi del binario e dalla composition root; dove un’impostazione non può essere confermata nei sorgenti, non è elencata qui.

I segreti che collegano sorgenti reali e custodiscono chiavi reali restano in file gestiti dall’operatore o segreti montati referenziati da variabile d’ambiente — mai nel datastore. Per il percorso eseguibile end-to-end, vedi la guida self-host; per l’elenco completo dei flag, vedi il riferimento CLI.

Il sottocomando `serve`

olivares serve esegue il server HTTP REST/web e il server gRPC in un unico processo, con la console web servita dalla stessa origine dell’API. Questi sono gli input di configurazione comuni.

TLS è attivo per default. Senza --tls-cert/--tls-key forniti, il motore assicura un certificato self-signed nella directory dati una volta, in anticipo, prima che qualsiasi listener accetti una connessione — cosi sia il server HTTP che gRPC usano lo stesso certificato e nessuno dei due ripiegare sul testo chiaro. Quando genera quel certificato registra l’impronta SHA-256 cosi i client possono fidarsi o fissarla.

--insecure e l’unico modo per servire in testo chiaro, e il percorso gRPC fallisce chiuso: al di fuori di --insecure il server rifiuta di costruire un listener in testo chiaro anziché degradare silenziosamente. Usalo solo su 127.0.0.1 durante lo sviluppo locale.

--seed-demo configura un amministratore demo con una password pubblica nel tree dei sorgenti e dati di estate fabbricati — solo per demo ed E2E. Il motore rifiuta di avviarlo se uno dei listener e non-loopback. Usa una directory dati temporanea.

Un secondo livello di flag governa le topologie distribuite e mutual-TLS — --admin-dsn e --allow-privileged-db-role (Postgres), --grpc-client-ca (mutual TLS dei collector), e --region/--known-regions (residenza dati). Questi sono coperti sotto e elencati per intero nel riferimento CLI.

Variabili d’ambiente

Il motore legge un numero ridotto di variabili d’ambiente all’avvio. Quelle sotto sono confermate nella composition root e nel wiring.

Directory dati e sorgenti

| Variabile | Effetto | | —- | —- | | OLIVARES_DATA_DIR | Directory dati predefinita quando --data-dir non è fornito (ripiega su ./olivares-data). Contiene la chiave di firma dell’audit, il materiale TLS e il file del datastore SQLite. Persistila tra i riavvii. | | OLIVARES_SOURCES_CONFIG | Percorso a un file JSON che collega sorgenti di osservazione reali, provider di roster di identità e sorgenti di documenti di conoscenza prima dell’avvio del motore. |

OLIVARES_SOURCES_CONFIG e l’unico input attraverso cui le sorgenti di segnale non-demo e i provider di roster vengono risolti. È la configurazione dell’operatore che porta segreti ed è deliberatamente tenuta fuori dal datastore. Il motore la legge all’avvio e registra ogni sorgente prima che il runtime parta.

La gestione è onesta anziché fail-fast. Una variabile mancante, un file illeggibile o con JSON non valido, o una lista di sorgenti configurata ma vuota tutti avvisano e producono una configurazione vuota — il motore non interrompe mai l’avvio. Una sorgente non configurata mostra un avviso anziché crashare il piano o fingere di funzionare: senza nulla cablato, la mappa degli accessi resta semplicemente vuota. Per popolarla, configura almeno una sorgente — vedi collegare una sorgente e, per il percorso cooperativo Claude Code, collegare Claude Code.

Punto di decisione di autorizzazione

Il controllo di accesso nativo basato su attributi e su ruoli governa sempre. Un punto di decisione di policy (PDP) esterno, quando selezionato, e un ulteriore livello solo restrittivo che può solo restringere la decisione che RBAC integrato ha già preso — mai ampliarla.

Due adattatori siedono dietro un unico seam — un valutatore Cedar incorporato (il percorso pure-Go) e un adattatore OPA-via-HTTP. Se OLIVARES_PDP_ENGINE seleziona un motore ma la sua configurazione e invalida (un file Cedar illeggibile, un target OPA malformato), il motore disabilita solo il PDP esterno, mantiene il motore ABAC nativo e RBAC in enforcement, e registra in modo evidente. Un file di policy rotto non lascia mai le richieste non governate e non crasha il piano. Per il modello deny-by-default, vedi governance.

Chiave di firma dell’audit

Il registro di audit e append-only, hash-chained, e ancorato da checkpoint firmati con Ed25519. La chiave di firma per evento viene risolta all’avvio, fail-closed per ogni sorgente custodita.

| Variabile | Effetto | | —- | —- | | OLIVARES_AUDIT_SIGNING_KEY | Chiave di firma fornita dal cliente, base64, inline. | | OLIVARES_AUDIT_SIGNING_KEY_FILE | Percorso a un segreto montato contenente la chiave (preferito — il valore non entra mai nell’ambiente del processo). | | OLIVARES_KEY_CUSTODY | Postura di custodia dichiarata (byok o cmek). Un avvio la cui custodia effettiva della chiave non corrisponde a quella dichiarata viene rifiutato. |

Senza nessuna di queste impostazioni, la chiave viene generata al primo avvio nella directory dati — il fallback onesto per singolo nodo / sviluppo. Condividere una chiave tra le repliche (tramite il valore env o un segreto montato) è necessario per l’alta disponibilità: altrimenti ogni nodo genera la propria e il registro si biforca al failover. La firma per evento resta sempre on-box. La custodia con wrapping KMS (chiave gestita dal cliente) e una postura aggiuntiva configurata tramite OLIVARES_KEY_WRAP; vedi il riferimento CLI.

Selezione del datastore

Il motore seleziona il suo datastore da --engine.

SQLite e il default e non necessita di alcun servizio esterno — e il datastore pronto per l’air-gap, a zero dipendenze per la topologia a singolo nodo, e quello su cui gira il deployment Docker Compose a un comando. Passa a Postgres quando hai bisogno di isolamento multi-tenant o scala orizzontale, non prima.

Scegliere postgres opta per il backstop di row-level-security che isola i tenant. Il motore rifiuta di avviarsi con un superuser Postgres o un ruolo BYPASSRLS — che disabiliterebbe quel backstop — a meno che --allow-privileged-db-role non sovrascriva esplicitamente la guardia (solo single-tenant / temporaneo). Per le letture System genuinamente cross-tenant (elenco organizzazioni, copertura checkpoint multi-tenant) fornisci un ruolo admin dedicato NOSUPERUSER BYPASSRLS tramite --admin-dsn; senza di esso quelle letture girano limitate da RLS e possono restituire vuoto. OLIVARES_DB_MAX_CONNS limita il pool applicativo per nodo.

Multi-tenancy e residenza

Una singola istanza è multi-tenant per costruzione su Postgres, con row-level security che isola i dati di ogni tenant. La residenza dei dati si sovrappone tramite --region.

Regione singola (default, senza --region): nessuna applicazione di residenza.
Regione specifica (--region eu, --region us, …): l’istanza serve solo tenant fissati alla sua regione di appartenenza e nega l’accesso cross-regione fail-closed. --known-regions elenca i codici regione validi per l’intero deployment; il pin di un tenant deve essere uno di essi, e una configurazione di regione malformata fa fallire l’avvio prima che il datastore si apra.

Checkpoint dell’audit

--checkpoint-interval controlla la frequenza di scrittura di un checkpoint firmato sulla catena di ogni tenant (default 1h; 0 disabilita). Un checkpoint finale viene scritto allo spegnimento pulito prima che il datastore si chiuda, cosi la catena e ancorata sia allo spegnimento che all’intervallo. Vedi verificare un rilascio per come la catena firmata viene verificata a valle.

Impostazioni sicure di default

Queste posture sono in vigore senza alcuna configurazione oltre a serve. Sono la postura predefinita del prodotto, non un hardening opzionale.

| Area | Default | Cosa significa | | —- | —- | —- | | Credenziali | Nessuna distribuita | Nessun nome utente o password predefiniti. Al primo avvio senza utenti, il motore genera un token di setup monouso e lo stampa solo su stdout — mai nei log. | | Trasporto | TLS attivo | HTTP e gRPC servono su TLS; un certificato self-signed viene generato nella directory dati se nessuno e fornito, e la sua impronta viene registrata. | | Indirizzo di bind | Loopback | --listen e --grpc-listen hanno default 127.0.0.1. La raggiungibilità fuori host e una decisione deliberata dell’operatore. | | Modalità testo chiaro | Disattivata | --insecure e l’unico modo per servire in testo chiaro, e il percorso gRPC fallisce chiuso. Solo sviluppo locale. | | Seeding demo | Disattivato | --seed-demo e disattivato e rifiuta qualsiasi bind non-loopback, perché genera un amministratore demo con password pubblica. | | Telemetria verso casa | Disattivata | Il motore non chiama casa. Le connessioni in uscita esistono solo verso le sorgenti che configuri — che è ciò che rende possibile un piano di controllo air-gapped a zero uscita. |

I bind loopback significano che il motore non è raggiungibile fuori host finche non li cambi. Quando lo pubblichi — ad esempio mappando una porta host in Docker Compose — TLS e già attivo per proteggerlo; non abbinare un bind pubblicato con --insecure. Su un’installazione nuova il motore stampa un blocco FIRST-BOOT SETUP su stdout con il token di setup unico (leggilo dai log del container sotto Compose); l’amministratore lo usa per creare il primo utente, poi si autentica.

Per ciò che il prodotto osserva, dove governa è dove la copertura è a livelli, leggi trasparenza e limiti.

Il sottocomando serve