Skip to main content
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
FieldTypeDefaultDescription
enabledboolfalseEnable Hub connectivity
urlstringhttps://hub.ultra.securityHub API URL
gateway_idstringThis gateway’s unique ID (set by ultra link)
workspace_idstringLinked workspace ID (set by ultra link)
sync_intervalstring"60s"How often to sync traces/events to Hub
offline_modeboolfalseContinue operating if Hub is unreachable
deploy_keystringStatic API key for headless/CI deployments

​
Setting Up Hub Connection

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