Gateways

Register and manage Ultra gateways

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

Flag	Short	Default	Description
--workspace	-w		Workspace ID to link to
--name	-n	hostname	Name 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:

Status	Description
Online	Gateway is syncing and sending heartbeats
Offline	No heartbeat received recently
Pending	Gateway 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, 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.

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:

Column	Description
Client	Client name (for example, Claude Code, claude-ai)
Status	Whether the client is currently managed by Ultra
Version	Reported client version
Calls	Number of tool calls routed through this gateway from the client
Active	Timestamp 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