ultra install

Detect installed MCP agents and configure them to use Ultra as their MCP server.

Usage

ultra install [flags]

Flags

Flag	Short	Default	Description
`--agent`			Target agent (`claude`, `cursor`, `vscode`, `cline`, `claude_code`, `windsurf`, `goose`, `codex`, `grok`, `opencode`, `gemini`, `antigravity`, `roocode`, `amazonq`, `lmstudio`, `zed`, `ona`, `hermes`)
`--all`		`false`	Install into all detected MCP agents (non-interactive)
`--config`			Path to Ultra config file
`--no-backup`		`false`	Skip backup of existing agent config
`--yes`	`-y`	`false`	Skip confirmation prompt
`--list`	`-l`	`false`	List detected agents without installing

--agent replaces the former --client flag. --client and its -c shorthand remain as deprecated aliases and print a pointer to --agent when used.

Examples

# Interactive installation wizard
ultra install

# Install into Claude Desktop only
ultra install --agent claude

# Install into Cursor only
ultra install --agent cursor

# Install into Codex only
ultra install --agent codex

# Install into Grok Build only
ultra install --agent grok

# Install into Antigravity
ultra install --agent antigravity

# Install into Zed
ultra install --agent zed

# Install into Ona
ultra install --agent ona

# Install into Hermes
ultra install --agent hermes

# List detected agents without installing
ultra install --list

# Install into all detected agents (non-interactive, used by MDM)
ultra install --all

Supported Agents

Agent	Flag Value	Aliases
Claude Desktop	`claude`	`claude-desktop`, `claude_desktop`
Cursor	`cursor`
Codex	`codex`	`codex-cli`
Grok Build	`grok`	`grok-build`, `grok_build`
VS Code	`vscode`
Claude Code	`claude_code`	`claude-code`
Windsurf	`windsurf`
Goose	`goose`
OpenCode	`opencode`
Gemini	`gemini`
Antigravity	`antigravity`	`agy`
Roo Code	`roocode`	`roo-code`, `roo_code`
Amazon Q	`amazonq`	`amazon-q`, `amazon_q`
LM Studio	`lmstudio`	`lm-studio`, `lm_studio`
Zed	`zed`
Ona	`ona`
Hermes	`hermes`

What It Does

The install command writes Ultra as an MCP server entry in the agent’s configuration. For example, Claude Desktop’s config becomes:

{
  "mcpServers": {
    "ultra": {
      "command": "/usr/local/bin/ultra",
      "args": ["start"]
    }
  }
}

For Codex, the TOML config at ~/.codex/config.toml becomes:

[mcp_servers.ultra]
command = "/usr/local/bin/ultra"
args = ["start"]

For Hermes, the YAML config at ~/.hermes/config.yaml becomes:

mcp_servers:
  ultra:
    command: /usr/local/bin/ultra
    args:
      - start
    enabled: true

Existing connectors and any non-MCP top-level keys in the Hermes config are preserved. Connectors with enabled: false are filtered out when discovering existing entries. If --config is specified, the args include --config <path>.

Auto-linking with deploy keys

Ultra auto-links the device to Hub at install time when invoked via:

ultra install --all — used by MDM deployments to configure every detected agent in one shot
ultra install --agent ona — used by the Ona devcontainer entry point, which needs the device named before any MCP agent starts

After configuring agents, these paths check for a deploy key (via ULTRA_DEPLOY_KEY environment variable, config file, or managed preferences). If a deploy key is found, the device is linked immediately:

The device registers with the workspace scoped by the deploy key
Device identity (email, external ID) is resolved from available sources (MDM preferences, environment variables)
The device appears in the Hub dashboard before any MCP agent launches

For all other install paths — the interactive wizard, plain ultra install --yes, and per-agent installs other than Ona — the device links during the first ultra start instead. OAuth-authenticated users always link at ultra start, regardless of which install path was used.

Backups

By default, the existing agent config is backed up before modification. Use --no-backup to skip.

​Usage

​Flags

​Examples

​Supported Agents

​What It Does

​Auto-linking with deploy keys

​Backups

Usage

Flags

Examples

Supported Agents

What It Does

Auto-linking with deploy keys

Backups