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

​
Usage

​
Flags

​
Examples

​
Checks performed

​
System

  • Go Runtime — Go version and platform
  • Operating System — OS compatibility (macOS, Linux, Windows)

​
MCP clients

  • Claude Desktop — Installation and MCP config detection
  • Cursor — Installation and MCP config detection
  • VS Code — Installation and MCP config detection
  • Cline — Installation and MCP config detection
  • Claude Code — Installation and MCP config detection
  • Windsurf — Installation and MCP config detection
  • Goose — Installation and MCP config detection
  • Codex — Installation and MCP config detection
  • Grok Build — Installation and MCP config detection
  • OpenCode — Installation and MCP config detection
  • Gemini CLI — Installation and MCP config detection
  • Antigravity — Installation and MCP config detection
  • Roo Code — Installation and MCP config detection
  • Amazon Q Developer — Installation and MCP config detection
  • LM Studio — Installation and MCP config detection
  • Zed — Installation and MCP config detection
  • Ona — Workspace and MCP config detection
  • Hermes — Installation and MCP config detection

​
Configuration

  • Config Directory — Ultra config directory exists (~/.config/ultra/)
  • Config File — Ultra configuration file exists

​
Dependencies

  • Node.js — Required for npm-based MCP servers
  • Docker — Optional for containerized MCP servers

​
Output

Each check shows a status icon:
  • Pass — Check succeeded
  • Warning — Optional component missing or not configured
  • 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 gateway’s configuration, detected MCP clients, 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

​
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 gateway 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.