mc2-harness ● release 20260928-35

Un tenant è il tuo spazio privato nella knowledge base: i tuoi documenti e le tue regole per l'agente. Solo chi ha la tua chiave può leggerli o modificarli. In più ogni tenant legge le regole comuni a tutti, il "Playbook di Sistema".

Il kit harness è il framework operativo che installi nel tuo progetto: fa lavorare l'agente con le tue regole e la tua knowledge base.

Il progetto usa tre tipi di cartelle, con ruoli diversi e separati:

Struttura consigliata:

Passo 1 — Scegli tre cose

Passo 2 — Provisioning e richiesta chiavi

Chiedi all'amministratore dell'infrastruttura (o a una sessione harness amministrativa su home-server):

L'amministratore esegue il provisioning:

• genera la chiave API con lo strumento di mc2-embed: python3 src/mc2_embed/tools/new_api_key.py --name harness-progetto-x --tenant progetto-x;
• registra lo SHA-256 della chiave nel segreto Doppler MC2_EMBED_API_KEYS e sincronizza il servizio (job Jenkins hs-secrets-sync);
• pubblica il tenant e la Knowledge Base di base con il job tenant-publish (o bin/harness.py tenant create);
• crea o consegna i file vars.yaml e .env per la radice del tuo progetto.

Nei file di progetto troverai:

Passo 3 — Installa il kit (due comandi)

Prerequisiti: bash, curl, unzip, python3 con PyYAML. Apri un terminale nella radice:

Alla fine leggi Bootstrap completato: nella radice trovi release/ (il kit installato e wrapper) e cwd/ (la CWD di runtime dell'agente). Lo script scarica il bundle, ne verifica l'integrità SHA-256 e si autocancella. La chiave API NON viaggia verso il server di distribuzione.

Passo 4 — Usa l'agente

Si parte sempre da cwd/: lì l'agente trova AGENTS.md e gli strumenti per scaricare a runtime regole e conoscenza dal server. L'agente accede a ../vars.yaml e ../.env senza esporre segreti in sessione. Ogni --add-dir autorizza un repository sorgente: senza, l'agente non può accedere ai file. Con altri agenti (agy, opencode, ...) si usa l'opzione equivalente.

Passo 5 — Riempi la tua knowledge base (facoltativo)

All'inizio il tenant è vuoto. Dentro l'agente del progetto chiedi, per esempio:

L'agente la carica nel tuo tenant. Da lì puoi chiedergli cose come "cosa dice la KB su…".

Da una macchina fuori dall'home-server, la sola chiave API non basta: il servizio mc2-embed è pubblicato dietro oauth2-proxy, che protegge l'accesso con un login. Una richiesta priva di sessione o di un token riconosciuto riceve 401 dal proxy, prima ancora di arrivare a mc2-embed e alla verifica della chiave API.

Servono quindi due credenziali indipendenti, con ruoli diversi:

Le due chiavi sono indipendenti: la prima non funziona senza la seconda (il proxy blocca prima), la seconda non funziona senza la prima (il servizio rifiuta senza chiave applicativa valida).

S2S — Passo 1: chiave API (una tantum, la fa l'amministratore)

È lo stesso passo di provisioning già descritto sopra. L'amministratore, dal repository mc2-embed, esegue:

Il comando stampa la chiave una sola volta (formato mc2e_...) e la voce YAML da registrare. La chiave in chiaro va nel tuo .env come KB_API_KEY; il suo hash SHA-256 va nel segreto Doppler MC2_EMBED_API_KEYS, applicato con il job Jenkins hs-secrets-sync. Fino a qui, nulla cambia rispetto all'uso locale sull'home-server.

S2S — Passo 2: client OAuth2 machine-to-machine (una tantum, la fa l'amministratore)

Questa parte è nuova rispetto all'accesso locale e serve solo per l'uso da remoto. L'autenticazione per le macchine usa il grant client credentials (standard OAuth2, RFC 6749 §4.4): due stringhe, nessun token da firmare, nessuna libreria crittografica da installare. L'amministratore dell'infrastruttura:

1. crea un App Client dedicato alle macchine nell'authorization server del cluster, con il grant client_credentials abilitato;
2. ne annota client_id e client_secret generati;
3. ti consegna le due stringhe in modo sicuro — mai per email o chat in chiaro: come segreto allegato a un canale cifrato, o tramite un secret manager condiviso.

Conserva client_secret come faresti con KB_API_KEY: nel tuo .env, fuori da git, mai incollato in una chat o in un ticket.

S2S — Passo 3: configurare il tenant (una tantum, lo fai tu)

Nel tuo .env, oltre a KB_API_KEY, aggiungi le tre variabili che il kit usa per ottenere l'access token:

Con queste tre variabili presenti, harness.py ottiene da solo un nuovo access token ad ogni comando (version-check, pb, kb, ...): non c'è nulla da rigenerare a mano, nessun comando aggiuntivo prima di lanciare l'agente. Se sei sull'home-server (kb_url: http://127.0.0.1:8080) non le configuri affatto: oauth2-proxy non è mai davanti a quell'indirizzo, la sola X-API-Key basta come oggi.

Verifica manuale, se vuoi controllare le credenziali prima di lanciare l'agente:

Una risposta 200 con JSON conferma che entrambe le credenziali sono valide. Una pagina HTML di login al posto del JSON significa che il token è scaduto, mancante, o il client non è abilitato al grant client_credentials.

S2S — Trappole comuni

Dalla radice del progetto:

Oppure da dentro cwd/:

Se c'è una versione nuova del kit viene scaricata e la cartella cwd/ viene rigenerata mantenendo release/overrides/ e release/addons/. Se è già aggiornato non fa nulla.

1. Il file .env è la tua chiave. Non condividerlo, non incollarlo in chat, non metterlo su git: la radice NON è un repository, tienila fuori da git.
2. Hai perso la chiave o temi che l'abbia vista qualcuno? Chiedi di rigenerare la chiave di progetto-x: la vecchia smette di funzionare e la nuova finisce nel .env.
3. Non salvare niente in cwd/: a ogni aggiornamento viene ricreata da zero. Il lavoro sta nei sorgenti; eventuali personalizzazioni stabili vanno in release/overrides/ o release/addons/.