Rete e certificati di Devin air-gapped

Questa documentazione riguarda le distribuzioni di Devin per il governo federale. Torna alla documentazione di Devin

La CLI e Desktop air-gapped si connettono agli endpoint dei modelli definiti nel tuo file dei modelli, all’emittente del provider di identità indicato nel tuo file di autenticazione e agli eventuali server MCP configurati localmente. Questa pagina descrive i requisiti di rete di queste connessioni: attendibilità TLS, un proxy facoltativo e i codici che vengono visualizzati quando una connessione non riesce.

Requisiti TLS

Ogni base_url dei modelli e l’issuer SSO devono usare https://. Il semplice http:// è accettato solo per gli host di loopback (localhost, 127.0.0.0/8, [::1]).
I certificati vengono verificati tramite l’archivio di attendibilità del sistema operativo (Security.framework su macOS, l’archivio delle CA di sistema su Linux). Se i tuoi endpoint sono firmati da una CA già installata sulla workstation, non serve alcuna configurazione aggiuntiva.
Se i tuoi endpoint sono firmati da una CA privata non presente nell’archivio di attendibilità del sistema operativo, aggiungila tramite DEVIN_CA_BUNDLE come descritto di seguito. La CLI non disabilita mai la verifica dei certificati.

Rendere attendibile una CA privata con `DEVIN_CA_BUNDLE`

DEVIN_CA_BUNDLE indica un file PEM i cui certificati sono considerati attendibili in aggiunta all’archivio di attendibilità del sistema operativo. Si applica alle richieste di inferenza, ai probe di devin airgap doctor e a ogni richiesta che la CLI invia al tuo IdP durante l’accesso SSO e la riconvalida.

Prepara il bundle

Inserisci in un unico file PEM i certificati root della tua CA privata (ed eventuali certificati intermedi). Il file può contenere più blocchi -----BEGIN CERTIFICATE-----.

sudo install -m 0644 ./corp-root-ca.pem /etc/devin/ca-bundle.pem

Non è necessario che i tuoi endpoint condividano lo stesso certificato o la stessa CA. Esiste un solo bundle per l’intero processo dell’agente, valido per ogni connessione: se endpoint diversi sono firmati da CA private diverse, concatena tutte queste CA nello stesso file:

cat ./corp-root-ca.pem ./ml-platform-ca.pem ./idp-root-ca.pem | sudo tee /etc/devin/ca-bundle.pem > /dev/null
sudo chmod 0644 /etc/devin/ca-bundle.pem

Con questo bundle, https://vllm.corp.example (firmato da corp-root-ca), https://models.ml.example (firmato da ml-platform-ca) e il tuo IdP (firmato da idp-root-ca) risultano tutti attendibili. Per gli endpoint firmati da una CA già presente nell’archivio di attendibilità del sistema operativo non serve alcuna voce. Il file dei modelli non prevede campi per certificati o TLS specifici per modello, e non è possibile usare un bundle distinto per ciascun endpoint.

Esporta la variabile nell'ambiente dell'agente

export DEVIN_CA_BUNDLE=/etc/devin/ca-bundle.pem

La variabile deve essere visibile al processo che esegue l’agente. Per la CLI da terminale, impostala nel profilo della shell di ogni utente. Per Desktop, impostala come le variabili delle chiavi API dei modelli (vedi Variabili d’ambiente delle chiavi API): aggiungila all’impostazione devin.acp.agentEnv oppure, su macOS, usa launchctl setenv DEVIN_CA_BUNDLE /etc/devin/ca-bundle.pem (open non trasmette all’app l’ambiente della tua shell).

Verifica con doctor

devin airgap doctor

…
pass  CA bundle                                 /etc/devin/ca-bundle.pem (3 certificate(s))
pass  model 'llama-3.3-70b': endpoint reachability  GET https://vllm.corp.example/v1/models -> 200 OK (trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)
pass  model 'qwen3-vl-32b': endpoint reachability  GET https://models.ml.example/v1/models -> 200 OK (trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)
…

Il suffisso trusted only via DEVIN_CA_BUNDLE conferma che è il bundle a rendere attendibile l’endpoint: doctor ritenta la connessione a ogni endpoint raggiungibile usando solo l’archivio di attendibilità del sistema operativo e segnala se il tentativo non riesce a livello TLS. Se la variabile non è impostata, la riga del CA bundle riporta not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA).

Se il file non è leggibile, contiene una sezione PEM non valida o non contiene certificati, doctor segnala come non riuscito il controllo CA bundle con CFG004 e il messaggio del parser (ad esempio failed to read CA bundle '/etc/devin/ca-bundle.pem': No such file or directory). In fase di runtime la stessa condizione non è bloccante: la CLI stampa una riga warning: ignoring DEVIN_CA_BUNDLE: … e ripiega sull’archivio di attendibilità del sistema operativo. Di conseguenza, un errore di battitura nel percorso si manifesta come errori TLS NET003 verso i tuoi endpoint, anziché come errore di avvio. Correggi il bundle ed esegui di nuovo doctor.

Proxy

La CLI air-gapped gestisce il proxy in uscita allo stesso modo della Devin CLI standard. Per impostazione predefinita ("mode": "system"), rispetta le variabili d’ambiente HTTP_PROXY, HTTPS_PROXY, ALL_PROXY e NO_PROXY, nonché le impostazioni PAC/proxy automatico del sistema operativo. Per forzare l’uso di un proxy specifico o per escludere del tutto i proxy, aggiungi un blocco proxy al file di configurazione utente (config.json nella directory di configurazione condivisa di Devin; vedi Formati su disco):

{
  "proxy": {
    "mode": "manual",
    "url": "http://proxy.corp.example:8080",
    "no_proxy": "localhost,127.0.0.1,.corp.example"
  }
}

`mode`	Comportamento
`"system"` (predefinito)	Usa le variabili d’ambiente del proxy e le impostazioni PAC della piattaforma.
`"manual"`	Instrada tutto il traffico tramite `url` (`http://`, `https://` o `socks5://`). I proxy definiti nelle variabili d’ambiente vengono ignorati.
`"off"`	Connessione diretta; ignora tutte le impostazioni del proxy.

no_proxy si applica in tutte le modalità e usa la stessa sintassi della variabile d’ambiente NO_PROXY. Per configurare il proxy per tutti gli utenti di un host, inserisci lo stesso blocco proxy nel file dei criteri machine-wide system.json (/etc/devin/system.json su Linux, /Library/Application Support/Devin/system.json su macOS, C:\ProgramData\Devin\system.json su Windows); se proxy è definito in entrambi i file, la CLI non si avvia finché non rimuovi la copia dell’utente. Il riferimento completo delle opzioni è disponibile nel riferimento del file di configurazione della CLI. Un proxy che termina il TLS e firma nuovamente il traffico con la propria CA è considerato una CA privata: aggiungi il suo certificato a DEVIN_CA_BUNDLE. Le connessioni continuano a raggiungere solo le destinazioni elencate all’inizio di questa pagina: il proxy cambia il percorso, non l’insieme delle destinazioni.

Timeout

Connessione	Timeout
Probe di `devin airgap doctor` (connessione e totale)	10 secondi per richiesta
Richieste SSO all’IdP (rilevamento, token, JWKS)	30 secondi per richiesta
Richieste di inferenza	30 secondi per la connessione; la lettura viene interrotta dopo 300 secondi senza ricezione di dati

Un probe che supera il proprio timeout viene segnalato come NET005.

Codici NET

devin airgap doctor associa uno di questi codici a ogni probe di endpoint non riuscito. Sono gli stessi codici che troverai nelle richieste di assistenza. Il catalogo completo è disponibile nella pagina Codici di errore.

Codice	Significato	Cosa fare
`NET001`	La risoluzione DNS dell’host dell’endpoint non è riuscita.	Verifica l’hostname nel file dei modelli o nel file di autenticazione e assicurati che il resolver della workstation riesca a risolverlo (`getent hosts <host>` o `dig <host>`).
`NET002`	Impossibile stabilire la connessione TCP (rifiutata, reimpostata, non instradabile).	Verifica che la porta sia raggiungibile dalla workstation e che eventuali firewall o proxy la consentano.
`NET003`	Handshake TLS non riuscito (certificato non attendibile, scaduto o non corrispondente). Quando riesce a ottenerlo, Doctor aggiunge il certificato presentato dal server (`subject`, `issuer`, `expires`) e indica se `DEVIN_CA_BUNDLE` era attivo.	Se l’emittente è la tua CA privata, imposta o correggi `DEVIN_CA_BUNDLE`. Se il certificato è scaduto o il suo nome non corrisponde all’URL, correggi il certificato del server.
`NET004`	L’endpoint ha restituito uno stato HTTP di errore diverso da 401/403. Un `404` su `GET {base_url}/models` genera solo un avviso, perché alcuni server compatibili con OpenAI non implementano `/models`.	Verifica che `base_url` includa il prefisso corretto (di solito `/v1`) e che il server sia operativo.
`NET005`	Timeout della richiesta.	Verifica la latenza di rete e assicurati che l’endpoint non sia sovraccarico; il probe `/models` dovrebbe rispondere entro 10 secondi.
`NET006`	L’endpoint ha rifiutato le credenziali configurate (HTTP 401/403).	Verifica il valore della variabile d’ambiente indicata in `api_key.env` del modello.

Codice	Significato	Cosa fare
`CFG002`	La variabile d’ambiente indicata nel campo `api_key.env` di un modello non è impostata nell’ambiente dell’agente. Doctor salta i probe di rete per quel modello.	Esporta la variabile nell’ambiente da cui viene avviato l’agente; consulta File dei modelli.
`CFG004`	Il file `DEVIN_CA_BUNDLE` è mancante, illeggibile o non contiene certificati PEM validi.	Correggi il percorso o il contenuto del file; il messaggio riporta l’errore di parsing.

​Requisiti TLS

​Rendere attendibile una CA privata con DEVIN_CA_BUNDLE

​Proxy

​Timeout

​Codici NET

​Codici CFG correlati

Requisiti TLS

Rendere attendibile una CA privata con `DEVIN_CA_BUNDLE`

Proxy

Timeout

Codici NET

Codici CFG correlati