> ## 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.

# Hub Settings

> Configure Ultra Hub connection settings

The `hub` section of your Ultra config controls how this gateway connects to Ultra Hub for centralized management, telemetry sync, and team collaboration.

## Configuration Reference

```yaml theme={null}
hub:
  enabled: false
  url: "https://hub.ultra.security"
  gateway_id: ""          # Assigned by Hub during linking
  workspace_id: ""        # Workspace this gateway is linked to
  sync_interval: "60s"    # How often to sync (e.g., "60s", "5m")
  offline_mode: false     # Allow operation without Hub connectivity
  deploy_key: ""          # Static API key for CI/headless deployments
```

| Field           | Type   | Default                      | Description                                    |
| --------------- | ------ | ---------------------------- | ---------------------------------------------- |
| `enabled`       | bool   | `false`                      | Enable Hub connectivity                        |
| `url`           | string | `https://hub.ultra.security` | Hub API URL                                    |
| `gateway_id`    | string |                              | This gateway's unique ID (set by `ultra link`) |
| `workspace_id`  | string |                              | Linked workspace ID (set by `ultra link`)      |
| `sync_interval` | string | `"60s"`                      | How often to sync traces/events to Hub         |
| `offline_mode`  | bool   | `false`                      | Continue operating if Hub is unreachable       |
| `deploy_key`    | string |                              | Static API key for headless/CI deployments     |

## Setting Up Hub Connection

<Tabs>
  <Tab title="Client">
    You can set up Hub connection by asking your AI client:

    1. Create an account at [hub.ultra.security](https://hub.ultra.security) and set up a workspace
    2. Ask your client to connect:
       * *"Log in to Ultra Hub"*
       * *"Link this gateway to Ultra Hub"*
    3. **Restart your AI client** for the connection to take effect

    Once linked, Ultra automatically syncs your traces and audit events to Hub in the background. You can manage your gateway, invite team members, and view all MCP activity from the Hub dashboard.
  </Tab>

  <Tab title="Terminal">
    Hub connection is typically configured through CLI commands rather than editing the config directly:

    ```bash theme={null}
    # 1. Authenticate with Hub
    ultra login

    # 2. Link this gateway to a workspace
    ultra link

    # 3. Start Ultra — it will sync automatically
    ultra start
    ```

    These commands set `enabled`, `url`, `gateway_id`, `workspace_id`, and authentication tokens in your config.
  </Tab>
</Tabs>

## Authentication Methods

Ultra Hub supports two authentication methods:

### OAuth2 (Interactive)

For developer workstations. Run `ultra login` to authenticate via browser:

```bash theme={null}
ultra login
```

Tokens are stored in the config and refreshed automatically. If your session expires, Ultra prints a single warning and disables sync until you re-authenticate.

### Deploy Keys (Headless/CI)

For CI/CD pipelines and servers without browser access:

```bash theme={null}
# Set via environment variable
export ULTRA_DEPLOY_KEY=dk_xxxxxxxxxxxx

# Or in config
hub:
  deploy_key: "dk_xxxxxxxxxxxx"
```

Deploy keys start with the `dk_` prefix. The environment variable `ULTRA_DEPLOY_KEY` takes priority over the config value.

## Sync Behavior

When Hub is enabled and the gateway is linked, `ultra start` runs a background sync loop:

* **Traces and audit events** are synced to Hub at the configured interval
* **Heartbeats** are sent at half the sync interval (minimum 30 seconds)
* **Token refresh** happens automatically before sync operations
* If authentication fails permanently (e.g., revoked token), sync is disabled with a single warning message

## Self-Hosted Hub

To connect to a self-hosted Hub instance:

```bash theme={null}
ultra login --hub https://hub.mycompany.com
```

Or set in config:

```yaml theme={null}
hub:
  url: "https://hub.mycompany.com"
```

## Disconnecting

```bash theme={null}
# Unlink gateway (keeps auth tokens for future linking)
ultra unlink

# Full logout (clears all Hub credentials)
ultra logout
```