Hub Settings

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

Configuration Reference

hub:
  enabled: false
  url: "https://hub.ultra.security"
  gateway_id: ""          # Assigned by Hub during linking
  workspace_id: ""        # Workspace this device 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 device’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

Agent
Terminal

You can set up Hub connection by asking your agent:

Create an account at hub.ultra.security and set up a workspace
Ask your agent to connect:
- “Log in to Ultra Hub”
- “Link this device to Ultra Hub”
Restart your agent 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 device, invite team members, and view all MCP activity from the Hub dashboard.

Hub connection is typically configured through CLI commands rather than editing the config directly:

# 1. Authenticate with Hub
ultra login

# 2. Link this device 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.

Authentication Methods

Ultra Hub supports two authentication methods:

OAuth2 (Interactive)

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

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:

# 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 device 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:

ultra login --hub https://hub.mycompany.com

Or set in config:

hub:
  url: "https://hub.mycompany.com"

Disconnecting

# Unlink device (keeps auth tokens for future linking)
ultra unlink

# Full logout (clears all Hub credentials)
ultra logout

Getting Started

Ultra Hub

Observability

Concepts

Hub Settings

Configuration Reference

Setting Up Hub Connection

Authentication Methods

OAuth2 (Interactive)

Deploy Keys (Headless/CI)

Sync Behavior

Self-Hosted Hub

Disconnecting

​Configuration Reference

​Setting Up Hub Connection

​Authentication Methods

​OAuth2 (Interactive)

​Deploy Keys (Headless/CI)

​Sync Behavior

​Self-Hosted Hub

​Disconnecting

Configuration Reference

Setting Up Hub Connection

Authentication Methods

OAuth2 (Interactive)

Deploy Keys (Headless/CI)

Sync Behavior

Self-Hosted Hub

Disconnecting