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

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

Client

You can set up Hub connection by asking your AI client:

1. Create an account at 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.

Terminal

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

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

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

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

Or set in config:

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

Disconnecting

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

# Full logout (clears all Hub credentials)
ultra logout