Skip to main content
Start with these commands:
Set HARNESS_LOG=debug for more client diagnostics.
Run the native binary with --version, then confirm its directory is on the same PATH used to launch blue. doctor prints the path it detected for every supported harness.
Run the native CLI with --version, then use blue apply, blue status, or blue run to compare the inventory’s normalized native harness version and compatibility result with the organization’s version_requirement. blue doctor reports the configuration source, session, revision, allowed harnesses, and each detected path, version, and allowed/denied state, but not the compatibility profile. In an interactive terminal, approve Blue’s repair prompt to install the highest published release inside the policy and certified range, or ask an administrator to change the range.
Blue suppresses native update checks and automatic updates during wrapped launches when the policy has an explicit maximum or relies on Blue’s certified release ceiling. Updates remain enabled only for an explicit upper-bound-free range with Allow unverified versions selected. Running the harness directly or using an external package manager can still replace it. If the prompt returns, run command -v kimi, command -v opencode, or the corresponding command for the affected harness, then compare that path with the package manager’s global binary directory. Multiple installations can shadow one another on PATH. Current Blue repairs verify the same executable path detected before installation; npm-owned binaries use npm, OpenCode uses its detected upgrade command, and standalone Kimi uses its pinned official installer. If an older Blue client created a shadowed npm installation, remove that unused installation through its package manager after confirming it is not the active path.
Compare the installed native harness version with the package adapter’s variant ranges. Ranges must not overlap. Blue uses the adapter’s fallback fields when no variant matches; a variant-only adapter must contain a matching range. The last usable package activation is retained while the affected launch remains blocked.
Run blue verify and inspect whether another process changes the managed overlay after reconciliation. Identical desired and current values are skipped; recurring prompts indicate a real file or revision difference.
Run blue apply to reconcile managed values, and confirm you are not invoking an installed shim. Governed settings should live only in launch-scoped overlays.
The governance and LiteLLM users must have the same email. The deployment provisions and reconciles one managed key for that user; run blue gateway to retry it before fetching personalized policy.
Check the inference proxy and LiteLLM logs, confirm the proxy listens on the URL delivered by blue config, and verify that the managed key allows the configured model and wire protocol.
Confirm the global policy has a top-level session_upload block, apply the current revision, and finish a native agent session so its lifecycle hook runs. Then check Control API and object-storage logs for presign, upload, verification, and completion errors.
Run blue status to identify the package and harness. Confirm the archive URL is reachable, its configured SHA-256 matches the exact bytes, every adapter path exists, and a helper asset covers the current OS and architecture. A previous working version remains available when its adapter is still compatible, but the affected governed launch stays blocked until reconciliation succeeds.
blue status reports public package redirects and environment proxies are unsupported when a public package URL answers with a redirect. Blue downloads the recorded URL and never follows one. A GitHub release-asset URL always redirects to a short-lived signed URL, so the final URL is not a usable substitute; ask an administrator to republish the package from github:owner/repository@ref or a managed repository connection. See public repositories and archives.
package URL must resolve only to public addresses means this client’s resolver returned at least one non-public address for the package host; Blue rejects the whole answer set rather than falling back to the public addresses in it. Split-horizon or internal DNS that rewrites a public hostname causes this on an otherwise reachable host. The fix is a managed package source connection with its own host allowlist, not a client-side override.
Reconciliation detected local changes in metaharness-owned content and disabled the package without deleting those changes. Inspect the quarantine path reported by client status, preserve anything needed, and remove it manually when it is no longer useful.

​
Reset authentication

For an accessible session, this rotates to its latest token generation, revokes its gateway and refresh sessions, removes the local credential, and then starts a new device authorization flow. Closing or declining that authorization leaves you signed out. It does not delete configuration overlays or captured sessions. blue login on its own already asks the service whether the stored session still works, so it re-authorizes without --force whenever the service rejects it. A temporary identity or Control API outage stops before opening a browser and preserves a usable local session for retry. If the old refresh credential is permanently invalid, Blue tries to revoke that session’s gateway binding with its existing access token and then completes a normal replacement login. Other Blue sessions are not affected. An unauthorized cleanup response is treated as already revoked because dashboard-wide revocation invalidates both credentials together. Other cleanup failures produce a warning and the binding expires automatically. If the session may be compromised, ask an administrator to use Revoke sessions for the account before signing in again. To disconnect the deployment itself, use blue reset. Reset archives non-secret tenant state, removes active Blue-owned overlays, and prompts for a Control API URL the next time you run bare blue or an interactive blue <agent> command. See Reset a deployment.