Skip to main content
A gateway is an instance of Ultra running on a developer machine, CI server, or any other host. Gateways link to workspaces in Ultra Hub and sync their telemetry data.

​
Linking a Gateway

After logging in, link your gateway to a workspace: 
ultra link
The interactive flow:
  1. Fetches your available workspaces from Hub
  2. Lets you choose which workspace to link to
  3. Prompts for a gateway name (defaults to your hostname)
  4. Registers the gateway with Hub

​
Non-Interactive

# Link to a specific workspace
ultra link --workspace ws_xxxxxxxxxxxx

# With a custom gateway name
ultra link --name "My MacBook"

​
Flags

FlagShortDefaultDescription
--workspace-wWorkspace ID to link to
--name-nhostnameName for this gateway

​
Sync Lifecycle

Once linked, the gateway syncs with Hub during ultra start:
  1. Startup — Gateway connects to Hub and begins background sync
  2. Data sync — Traces and audit events are synced at the configured interval (default: 60s)
  3. Heartbeats — Sent at half the sync interval to report gateway health
  4. Token refresh — OAuth tokens are refreshed automatically when needed

​
Sync Configuration

hub:
  sync_interval: "60s"    # How often to sync
  offline_mode: false      # Continue if Hub is unreachable

​
Offline Mode

When offline_mode: true, Ultra continues operating normally even if Hub is unreachable. Data is stored locally and can be synced later.

​
Unlinking a Gateway

Remove the gateway’s connection to Hub: 
# Interactive (with confirmation)
ultra unlink

# Skip confirmation
ultra unlink --force
Unlinking:
  • Notifies Hub that this gateway is disconnecting
  • Clears the gateway ID and workspace ID from local config
  • Preserves authentication tokens (for future re-linking)
  • Keeps local data intact

​
Gateway Status

Hub tracks each gateway’s status:
StatusDescription
OnlineGateway is syncing and sending heartbeats
OfflineNo heartbeat received recently
PendingGateway registered but hasn’t synced yet

​
Re-Linking

To move a gateway to a different workspace: 
# Unlink from current workspace
ultra unlink

# Link to a new workspace
ultra link --workspace ws_new_workspace_id