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

​
Linking via Hub Web UI

You can also view and manage gateways from the Hub web interface:
  1. Navigate to your workspace in Hub
  2. The Gateways section shows all linked gateways with their status (Online, Offline, Pending)
  3. Gateway details include hostname, last sync time, and linked workspace
Gateway registration currently requires the CLI (ultra link). The web UI provides monitoring and management of existing gateways.

​
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