Troubleshoot Air-Gapped Devin: doctor Runbook

This documentation is for the federal deployments of Devin. Back to Devin Docs

devin airgap doctor is the first thing to run when the CLI or Desktop does not start, cannot reach a model, or shows an error code. It runs every local and network check the agent depends on, prints one line per check, and exits nonzero if anything fails. This page explains each check and what to do about it, then describes what to collect for a support request.

Run doctor

Run it as the user who will use Devin, in the same environment (the API-key variables must be set in that shell):

devin airgap doctor

pass  license                                seat alice@example.gov (account acme), expires 2027-03-01
pass  models file path                       /etc/devin/models.json
pass  config dir writable                    /home/alice/.config/devin/cli-federal
pass  data dir writable                      /home/alice/.local/share/devin/cli-federal
pass  CA bundle                              not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)
pass  models file parse                      1 model(s) configured
pass  model 'llama-3.3-70b': API key env var  LOCAL_LLAMA_API_KEY is set
pass  custom subagent profiles               none configured
pass  model 'llama-3.3-70b': endpoint reachability  GET https://models.internal:8000/v1/models -> 200 OK
pass  model 'llama-3.3-70b': inference conformance  POST https://models.internal:8000/v1/chat/completions -> 200 OK (412 ms)

10 check(s): 10 passed, 0 warning(s), 0 failure(s)

Each line is <status> <check> <detail>. Coded failures and warnings prefix the detail with the error code, for example FAIL model 'llama-3.3-70b': endpoint reachability NET003: ....

Status	Meaning	Exit status
`pass`	The check succeeded.
`warn`	Devin will run, but something needs attention soon (license expiring, `/models` not implemented, probe skipped).	`0`
`FAIL`	Devin will not work correctly until this is fixed.	nonzero, with `doctor found N failing check(s)`

For automation, --json prints {"ok": <bool>, "checks": [...]} where each check has check, status (pass, warn, fail), and detail, plus code on coded warnings and failures and latency_ms on a passing inference probe:

devin airgap doctor --json

{
  "ok": true,
  "checks": [
    {
      "check": "license",
      "status": "pass",
      "detail": "seat alice@example.gov (account acme), expires 2027-03-01"
    },
    {
      "check": "model 'llama-3.3-70b': inference conformance",
      "status": "pass",
      "detail": "POST https://models.internal:8000/v1/chat/completions -> 200 OK (412 ms)",
      "latency_ms": 412
    }
  ]
}

Desktop uses the same bundled CLI, so run doctor from a terminal on the Desktop host to diagnose Desktop problems too.

Check reference

Checks run in the order below. Later checks that depend on an earlier failure are skipped rather than repeated: if the models file cannot be found, there is no models file parse line and no endpoint probes.

`license`

Loads and verifies the license file (see License).

Result	Detail	Action
`pass`	`seat <label> (account <id>), expires <YYYY-MM-DD>`	None.
`warn`	`... (<n> day(s) left) — contact your administrator to renew it` when fewer than 30 days remain; `(less than a day left)`; or `already expired (within the clock-skew grace period)`	Renew and replace the license before the 24-hour grace period ends.
`FAIL`	`LIC00n: <message>` followed by `Checked <path> — install a valid license there or point DEVIN_LICENSE_FILE at one.`	Follow the `LIC` row in Error codes.

`models file path`

Resolves the models file location (/etc/devin/models.json, C:\ProgramData\Devin\models.json on Windows, or DEVIN_MODELS_FILE) and confirms a file exists there.

Result	Action
`pass` with the resolved path	None.
`FAIL CFG003`	Install the models file or fix the `DEVIN_MODELS_FILE` value. All models-file and endpoint checks are skipped.

`config dir writable` and `data dir writable`

Creates the product config and data directories if needed and writes a probe file to each.

Result	Action
`pass` with the directory path	None.
`FAIL CFG001`	The detail says whether the directory could not be resolved, created, or written. Fix ownership and permissions for the user running Devin, or set `XDG_CONFIG_HOME` / `XDG_DATA_HOME` to a writable location. On Windows the CLI does not read `XDG_*`; fix the permissions on `%APPDATA%\devin\`.

`CA bundle`

Reports whether DEVIN_CA_BUNDLE is set and loads it.

Result	Detail	Action
`pass`	`not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)`	None, unless your endpoints use a private CA.
`pass`	`<path> (<n> certificate(s))`	None.
`FAIL CFG004`	Why the file could not be loaded	Fix the path or the PEM contents; see Network and certificates.

`models file parse` and `model '<name>': API key env var`

Parses the models file with the same validator as devin models validate, then checks that each model’s api_key.env variable is set in the current environment.

Result	Action
`pass models file parse <n> model(s) configured`	None.
`FAIL models file parse <message> (run devin models validate for structured MDL diagnostics)`	Run `devin models validate` and fix each `MDL` code; see Models file. Endpoint probes are skipped.
`pass model '<name>': API key env var <VAR> is set`	None.
`FAIL CFG002 environment variable '<VAR>' (referenced by api_key.env) is not set`	Export the variable in this shell, or for Desktop add it to `devin.acp.agentEnv`; see API key environment variables. The endpoint probes for that model are skipped with a `warn`.

`custom subagent profiles`

Lists custom subagent definitions from agents/**/AGENT.md. none configured or <n> profile(s) loaded passes; CFG005 names a definition that could not be parsed. This check is shared with the standard devin doctor and is unrelated to the air-gapped configuration.

`model '<name>': endpoint reachability`

Sends GET {base_url}/models with the model’s API key, using a 10-second timeout and the same TLS configuration inference uses.

Result	Detail	Action
`pass`	`GET <url> -> 200 OK`	None. If the detail adds `(trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)`, the bundle is load-bearing: keep it configured on every host.
`warn NET004`	`GET <url> -> 404 Not Found (server may not implement /models)`	None; the endpoint is reachable and the inference probe below is the real test.
`warn CFG002`	`skipped: API key env var '<VAR>' is not set`	Set the variable (see above).
`FAIL NET006`	`GET <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'`	The variable is set but its value is wrong for this endpoint.
`FAIL NET004`	`GET <url> -> <status>`	Check the endpoint’s logs and the `base_url` path.
`FAIL NET001` / `NET002` / `NET005`	DNS, TCP, or timeout error chain	Check name resolution, firewall and proxy rules, and endpoint health from the same workstation.
`FAIL NET003`	TLS error chain, then the certificate the server presented (subject, issuer, expiry), then either `TLS failed despite the configured DEVIN_CA_BUNDLE (<path>) — verify the bundle contains this endpoint's CA` or `if this endpoint uses a private CA, set DEVIN_CA_BUNDLE=/path/to/ca.pem`	Compare the printed issuer with the certificates in your bundle; see Network and certificates.

`model '<name>': inference conformance`

Skipped when reachability failed at the transport level. Sends a one-token request to prove the endpoint speaks the configured API: POST {base_url}/chat/completions with max_tokens: 1 for chat_completions, or POST {base_url}/responses with max_output_tokens: 16 for responses.

Result	Detail	Action
`pass`	`POST <url> -> 200 OK (<n> ms)`	None. The latency is a useful baseline for later comparisons.
`FAIL NET006`	`POST <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'`	Fix the key.
`FAIL NET004`	`POST <url> -> <status>: <first 200 characters of the response body>`	The body usually names the problem: unknown model name (the request uses the `name` from your models file, which must match what the server serves), wrong `api` value for this server, or a server-side error.
`FAIL NET00n`	Transport error chain	As for reachability.

Common problems

Symptom	Likely cause	Where to look
Doctor passes in a terminal but Desktop cannot reach the model	Desktop’s bundled agent does not inherit your shell environment, so the API-key variable is unset	API key environment variables
Every user on a host passes except one	Per-user state: permissions on `~/.config/devin` or `~/.local/share/devin` (`%APPDATA%\devin` on Windows), or a stale `sso_tokens.toml` (`IDP006`)	On-disk formats
`devin auth login` succeeds but sessions end after a while	Revalidation failed: the user was removed from `required_group` or the IdP session was revoked	SSO and the `sso_revalidation_failed` audit event
`NET003` only on some hosts	`DEVIN_CA_BUNDLE` not set, or a different bundle, on those hosts	Network and certificates
`LIC004` after installing an update, or on a new environment	Build and license come from different environments, or a key rotation	License: check the key ID
`MDL014` when saving models in Desktop	The models file is owned by root or another user (on Windows, by an administrator while you are a standard user)	Edit the file on disk as its owner

What to send to support

Collect the following on the affected workstation. Review each file before sending it; none of them is uploaded automatically.

The doctor output:

devin airgap doctor --json > doctor.json

(no output; the command exits nonzero if a check failed)

The detail strings contain your endpoint URLs and hostnames but never API-key values.

The redacted diagnostics report:
devin diagnostics --output devin-diagnostics.txt
Diagnostics written to devin-diagnostics.txt The report is plain text and stays on this machine; review it before sharing.
The report records versions, whether each configuration file exists and parses, model names, whether each API-key variable is set, and audit-log statistics. It never contains prompts, code, file contents, secret values, endpoint URLs, or environment-variable values.
The exact error message shown to the user, including its code, and the output of devin --version.
For SSO problems, the relevant auth events from the audit log (error_code and action fields) and the matching entries from your IdP’s logs.

Do not send the license file, the API-key values, sso_tokens.toml, or sessions.db.

​Run doctor

​Check reference

​license

​models file path

​config dir writable and data dir writable

​CA bundle

​models file parse and model '<name>': API key env var

​custom subagent profiles

​model '<name>': endpoint reachability

​model '<name>': inference conformance

​Common problems

​What to send to support

Run doctor

Check reference

`license`

`models file path`

`config dir writable` and `data dir writable`

`CA bundle`

`models file parse` and `model '<name>': API key env var`

`custom subagent profiles`

`model '<name>': endpoint reachability`

`model '<name>': inference conformance`

Common problems

What to send to support