ultra doctor

Run diagnostic checks to verify Ultra is properly configured. Optionally upload a sanitized diagnostics report to Ultra Hub for fleet debugging.

Usage

ultra doctor [flags]

Flags

Flag	Short	Default	Description
`--verbose`	`-v`	`false`	Show detailed output
`--debug`		`false`	Show detailed detection diagnostics
`--report`		`false`	Upload a sanitized diagnostics report to Ultra Hub
`--dry-run`		`false`	With `--report`, print the payload to stdout instead of uploading

Examples

# Run diagnostics
ultra doctor

# Show detailed output
ultra doctor --verbose

# Upload a diagnostics report to Hub
ultra doctor --report

# Preview the report payload without uploading
ultra doctor --report --dry-run

Checks performed

Checks are grouped into four sections: System, Agents, Configuration, and Dependencies.

System

Check	What it reports
Go Runtime	Go version and platform
Operating System	OS compatibility (macOS, Linux, Windows)

Agents

Doctor lists a row only for the agents it detects on this machine, either because the agent is installed or because its config was found. Supported agents that aren’t detected are left out. See Supported Agents for the full list, including Claude Desktop, Cursor, VS Code, Claude Code, and Codex. Each agent row shows one of these results:

Result	Status	Meaning
`3 connectors`, `1 connector`, or `no connectors`	Pass	Ultra read the agent’s MCP config. The count includes every MCP connector in it, Ultra included
`no MCP config`	Warning	The agent is installed but has no MCP config yet. Run `ultra install --agent <agent>` to configure it
`config detected, binary not in PATH`	Warning	Ultra found the agent’s config directory but couldn’t locate the agent itself
`config parse failed`	Warning	Ultra couldn’t parse the agent’s config file. The file path and the parser’s error appear under the row, even without `--verbose`. Fix the file, then run `ultra doctor` again

The Agents section always ends with a Config Drift check, which looks for MCP connectors that aren’t running through Ultra:

Result	Status	Meaning
`2 agent(s) fully managed`	Pass	At least one agent is fully managed, and no detected agent has connectors outside Ultra
`1 agent(s) with unmanaged connectors`	Warning	At least one agent has connectors outside Ultra. With `--verbose`, and under Recommendations, doctor lists each agent and its unmanaged connectors
`no agents migrated yet`	Warning	No detected agent is fully managed yet. Run `ultra install`, then `ultra migrate`

Configuration

Check	What it reports
Config Directory	Ultra config directory exists (`~/.config/ultra/`, or `%APPDATA%\ultra` on Windows)
Config File	Ultra configuration file exists

Dependencies

Check	What it reports
Node.js	Required for npm-based MCP connectors. A warning if it isn’t found
Docker	Optional, for containerized MCP connectors. A missing Docker passes as `not installed (optional)`. Doctor warns only when Docker is installed but `docker --version` fails (`unavailable`) or doesn’t respond (`timed out`)

Output

Each check shows a status icon:

Pass: Check succeeded, or an optional component such as Docker isn’t installed
Warning: Something needs attention, such as an agent config Ultra couldn’t parse or a missing Node.js
Error: Required component missing or broken

The summary shows total checks, passes, warnings, and errors, with recommendations for any issues found.

Diagnostics reporting

When you pass --report, Ultra collects a sanitized snapshot of your device’s configuration, detected MCP agents, and recent log artifacts, then uploads the bundle to Ultra Hub. This helps your organization’s admins and Ultra support diagnose installation or connectivity issues across a fleet of machines.

What is collected

Section	Contents
Config snapshot	Your `ultra.yaml` with tokens, secrets, and environment variables masked as `[REDACTED]`
Detected agents	Which MCP agents are installed, whether Ultra is configured in each, and any detection errors
Hub state	Whether the device is linked, the workspace ID, sync interval, and offline mode setting
Log artifacts	The last 16 KB of `sync.log`, `crash.log`, post-install log, and setup agent log (if present)
Managed preferences	Whether MDM-managed keys (`AutoSetup`, `DeployKey`, etc.) are present on macOS
System info	Ultra version, OS, and architecture

Privacy and redaction

The diagnostics payload is automatically redacted before it leaves your machine:

API keys, tokens, and secrets are replaced with [REDACTED]
Your home directory path is replaced with ~
Hostnames are replaced with [REDACTED_HOSTNAME]
Credential patterns (Bearer tokens, JWTs, AWS keys, GitHub tokens, PEM private keys, database URLs) are detected and scrubbed

Use --report --dry-run to inspect the exact payload before uploading.

Requirements

The device must be authenticated with Ultra Hub (ultra login)
The report is uploaded to POST /api/v1/diagnostics and stored in S3 for Ultra employees only
A gateway.diagnostics_reported security event appears in your organization’s Admin Log when --report is used manually

Automatic background diagnostic uploads (during install auto-link, for example) do not create Admin Log entries.

​Usage

​Flags

​Examples

​Checks performed

​System

​Agents

​Configuration

​Dependencies

​Output

​Diagnostics reporting

​What is collected

​Privacy and redaction

​Requirements

Usage

Flags

Examples

Checks performed

System

Agents

Configuration

Dependencies

Output

Diagnostics reporting

What is collected

Privacy and redaction

Requirements