> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ultra.security/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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

```bash theme={null}
# 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

```yaml theme={null}
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:

```bash theme={null}
# 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                                                      |
| **Idle**    | No heartbeat received recently — the gateway is between sync cycles or temporarily unreachable |
| **Pending** | Gateway registered but hasn't synced yet                                                       |

## Auto-linking with deploy keys

When a [deploy key](/hub/deploy-keys) 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](/installation/mdm-deployment) 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:

| 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:

```bash theme={null}
# Unlink from current workspace
ultra unlink

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