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
IdleNo heartbeat received recently — the gateway is between sync cycles or temporarily unreachable
PendingGateway registered but hasn’t synced yet

​
Auto-linking with deploy keys

When a deploy key is configured, the gateway links automatically without any manual ultra link step. This happens at one of two points:
  • At install time — ultra install --all (used by MDM deployments) and ultra install --client ona link the gateway immediately, so it appears in Hub before any MCP client opens
  • At ultra start — for all other paths (the interactive wizard, ultra install --yes, and per-client installs other than Ona), the gateway links on first startup
Both paths register the gateway to the workspace scoped by the deploy key. See the MDM Deployment Guide for the full setup.

​
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, Idle, 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.

​
Gateway detail panel

Click any gateway row in the Gateways list to open a slide-out detail panel with:
  • Host — Operating system, architecture (e.g., ARM64), hostname, gateway version, and gateway type (Personal, Team, etc.).
  • Environment — The environment the gateway runs in (Local, Dev, Prod, etc.).
  • Activity — Status (Online, Idle, Offline), last-seen timestamp, creation date, and linked workspace.
  • Health — Enforcement profile, last configuration scan time, the count of fully-managed MCP servers (e.g., 5 / 5), and the number of drift events detected.
  • Clients — A table of MCP clients connected to this gateway:
ColumnDescription
ClientClient name (for example, Claude Code, claude-ai)
StatusWhether the client is currently managed by Ultra
VersionReported client version
CallsNumber of tool calls routed through this gateway from the client
ActiveTimestamp of the most recent activity
Use this view to confirm which host a gateway is running on, which workspace it belongs to, whether its configuration is in a healthy state, and which clients are talking to it.

​
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