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

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.

​
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