sintropi-bootstrap 2605.12.1016

Bootstrap and launcher for the sintropi-code CLI — authenticates via Keycloak PKCE and pulls the right engine version from each Sintropi gateway.

sintropi-bootstrap

Bootstrap pubblico per la CLI sintropi-code — l'engine multi-agent di Sintropi.

Permette a uno sviluppatore di installare, autenticare e mantenere allineata la versione di sintropi-code corretta per ogni ambiente Sintropi (dev, qa, prod, tenant cliente).

Installazione

pip install sintropi-bootstrap

Uso

# Primo setup o switch ambiente (idempotente)
sintropi-bootstrap https://gateway.acme.eight20.com

# Comando principale — auto-detect versione, auto-download se cambiata
sintropi-code generate "App per la gestione ordini"
sintropi-code bootstrap my-app -o ./output/my-app

Come funziona

1. sintropi-bootstrap <gateway>

   • Legge GET {gateway}/api/bootstrap/config (pubblico) → { keycloak_url, realm, client_id, current_sha, current_version }
   • Avvia Authorization Code + PKCE su loopback http://localhost:PORT (RFC 8252) — apre il browser sulla pagina Keycloak standard
   • Verifica che l'utente abbia il ruolo realm sintropi-code
   • Scarica il wheel via GET {gateway}/api/bootstrap/download (Bearer JWT)
   • Crea un venv isolato in ~/.sintropi/versions/{sha}/.venv/ e ci installa sintropi-agents
   • Registra il gateway in ~/.sintropi/config.json

2. sintropi-code [args]

   • Legge il gateway corrente da ~/.sintropi/config.json
   • Verifica (con cache TTL 5 min) il SHA dell'engine corrente del gateway
   • Se diverso o assente → re-auth + download + install (transparente)
   • exec in ~/.sintropi/versions/{sha}/.venv/bin/python -m sintropi_agents.main <args>

Layout filesystem

~/.sintropi/
├── credentials.json    # token per-gateway (chmod 600)
├── config.json         # gateway noti + current + ultimo check
└── versions/
    ├── {sha-abc123}/
    │   ├── .venv/      # venv isolato con sintropi-agents installato
    │   └── manifest.json
    └── {sha-def456}/
        ├── .venv/
        └── manifest.json

Ogni gateway può avere una versione diversa dell'engine. La cache locale supporta più ambienti simultaneamente: switchare è istantaneo se la versione è già scaricata.

Switch ambiente

sintropi-bootstrap è idempotente. Rilanciarlo con un URL diverso fa lo switch:

sintropi-bootstrap https://gateway.dev.acme.eight20.com    # ambiente dev
sintropi-code generate "..."

sintropi-bootstrap https://gateway.prod.acme.eight20.com   # switch a prod
sintropi-code generate "..."   # ora usa l'engine di prod

In alternativa, override puntuale con flag:

sintropi-code --gateway https://gateway.qa.acme.eight20.com generate "..."

Permesso negato (ruolo mancante)

Per scaricare l'engine serve il ruolo realm Keycloak sintropi-code. Se sei loggato ma il ruolo non è assegnato, sintropi-bootstrap (e sintropi-code) stampano un riquadro con le istruzioni:

────────────────────────────────────────────────────────────────────────
 Permesso negato: ruolo mancante
────────────────────────────────────────────────────────────────────────

 Utente:        [e-mail]
 Realm:         acme
 Ruolo serve:   sintropi-code

 Come richiedere l'accesso:

 1. Contatta l'amministratore Keycloak del realm 'acme' e chiedi
    di assegnarti il ruolo realm 'sintropi-code'.

 2. L'admin può farlo dalla console Keycloak:
    https://auth.acme.eight20.com/admin/acme/console/
    → Users → [e-mail] → Role mapping → Assign role → sintropi-code

 3. Una volta assegnato il ruolo, rilancia lo stesso comando:
    il token verrà rinnovato automaticamente e il download partirà.

L'errore esce con exit code 2.

Uso da Claude Cowork (Claude Desktop)

TL;DR — Claude Cowork in modalità Desktop standard esegue le operazioni direttamente sul computer locale dell'utente. In questo scenario sintropi-bootstrap usa un normale flow OAuth2 PKCE locale e non richiede alcun tunnel SSH.

Caso standard (Cowork locale)

Tutto avviene sullo stesso PC dell'utente:

• Terminale locale aperto da Cowork
• Browser di default locale per la pagina di login Keycloak
• Loopback http://localhost:PORT per il callback OAuth
• Cache ~/.sintropi/ persistente nell'home utente

L'utente può chiedere a Cowork: "Installa sintropi-code, agganciati al gateway https://gateway.acme.eight20.com e genera un'app in ~/projects/contracts-app". Cowork mostra il piano (pip install + sintropi-bootstrap + sintropi-code generate), chiede approvazione e lo esegue. Niente configurazione di rete extra.

Caso avanzato (shell remota / cloud)

Solo se la shell in cui gira sintropi-bootstrap non è sullo stesso host del browser:

• SSH verso una VM remota / container remoto / cloud shell
• CI/CD job che vuole installare l'engine
• Claude Code in versione web-hosted (non Cowork Desktop)

In questi scenari serve esporre il loopback verso la workstation dell'utente con un tunnel SSH -L. L'URL Keycloak viene stampato in console: lo apri dal browser locale, completi il login, il redirect torna sul tunnel al loopback remoto.

Raccomandazioni per ambienti remoti condivisi:

• usare un account utente personale (non shared) per l'autenticazione
• non lasciare ~/.sintropi/credentials.json su host non personali
• se possibile, preferire l'esecuzione locale (Cowork Desktop) e poi sincronizzare il risultato

Sicurezza

• Client public + PKCE: nessun secret nel pacchetto né nella cache
• Loopback: il redirect torna su http://localhost:PORT random, niente esposizione di rete
• State + PKCE verifier: protezione CSRF e code interception
• Role check server-side: il gateway nega il download senza ruolo sintropi-code
• SHA-256 verificato sul wheel scaricato (oltre al TLS)

Licenza

Proprietary — © Eight20.