ultra install

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

Usage

ultra install [flags]

Flags

Flag	Short	Default	Description
`--client`	`-c`		Target client (`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 clients (non-interactive)
`--config`			Path to Ultra config file
`--no-backup`		`false`	Skip backup of existing client config
`--yes`	`-y`	`false`	Skip confirmation prompt
`--list`	`-l`	`false`	List detected clients without installing

Examples

# Interactive installation wizard
ultra install

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

# Install into Cursor only
ultra install --client cursor

# Install into Codex only
ultra install --client codex

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

# Install into Antigravity
ultra install --client antigravity

# Install into Zed
ultra install --client zed

# Install into Ona
ultra install --client ona

# Install into Hermes
ultra install --client hermes

# List detected clients without installing
ultra install --list

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

Supported Clients

Client	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 client’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 servers and any non-MCP top-level keys in the Hermes config are preserved. Servers 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 gateway to Hub at install time when invoked via:

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

After configuring clients, 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 gateway is linked immediately:

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

For all other install paths — the interactive wizard, plain ultra install --yes, and per-client installs other than Ona — the gateway 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 client config is backed up before modification. Use --no-backup to skip.

​Usage

​Flags

​Examples

​Supported Clients

​What It Does

​Auto-linking with deploy keys

​Backups