> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ultra.security/llms.txt
> Use this file to discover all available pages before exploring further.

# ultra install

> Install Ultra into MCP clients

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

## Usage

```bash theme={null}
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

```bash theme={null}
# 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:

```json theme={null}
{
  "mcpServers": {
    "ultra": {
      "command": "/usr/local/bin/ultra",
      "args": ["start"]
    }
  }
}
```

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

```toml theme={null}
[mcp_servers.ultra]
command = "/usr/local/bin/ultra"
args = ["start"]
```

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

```yaml theme={null}
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](/hub/deploy-keys) (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.