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

# Devices

> Register and manage Ultra devices

A **device** is an instance of Ultra running on a developer machine, CI server, or any other host. Devices link to workspaces in Ultra Hub and sync their telemetry data.

## Linking a Device

After logging in, link your device 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 device name (defaults to your hostname)
4. Registers the device with Hub

### Non-Interactive

```bash theme={null}
# Link to a specific workspace
ultra link --workspace ws_xxxxxxxxxxxx

# With a custom device name
ultra link --name "My MacBook"
```

## Flags

| Flag          | Short | Default  | Description             |
| ------------- | ----- | -------- | ----------------------- |
| `--workspace` | `-w`  |          | Workspace ID to link to |
| `--name`      | `-n`  | hostname | Name for this device    |

## Sync Lifecycle

Once linked, the device syncs with Hub during `ultra start`:

1. **Startup** — Device 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 device 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 Device

Remove the device's connection to Hub:

```bash theme={null}
# Interactive (with confirmation)
ultra unlink

# Skip confirmation
ultra unlink --force
```

Unlinking:

* Notifies Hub that this device is disconnecting
* Clears the device ID and workspace ID from local config
* Preserves authentication tokens (for future re-linking)
* Keeps local data intact

## Device Status

Hub tracks each device's status:

| Status      | Description                                                                                   |
| ----------- | --------------------------------------------------------------------------------------------- |
| **Online**  | Device is syncing and sending heartbeats                                                      |
| **Idle**    | No heartbeat received recently — the device is between sync cycles or temporarily unreachable |
| **Pending** | Device registered but hasn't synced yet                                                       |

## Auto-linking with deploy keys

When a [deploy key](/hub/deploy-keys) is configured, the device 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 --agent ona` link the device immediately, so it appears in Hub before any MCP agent opens
* **At `ultra start`** — for all other paths (the interactive wizard, `ultra install --yes`, and per-agent installs other than Ona), the device links on first startup

Both paths register the device 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 devices from the Hub web interface:

1. Navigate to your workspace in Hub
2. The **Devices** section shows all linked devices with their status (Online, Idle, Pending)
3. Device details include hostname, last sync time, and linked workspace

Device registration currently requires the CLI (`ultra link`). The web UI provides monitoring and management of existing devices.

### Device detail panel

Click any device row in the Devices list to open a slide-out detail panel with:

* **Host** — Operating system, architecture (e.g., `ARM64`), hostname, device version, and device type (`Personal`, `Team`, etc.).
* **Environment** — The environment the device 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 connectors (e.g., `5 / 5`), and the number of drift events detected.
* **Agents** — A table of MCP agents connected to this device:

| Column      | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| **Agent**   | Agent name (for example, `Claude Code`, `claude-ai`)           |
| **Status**  | Whether the agent is currently managed by Ultra                |
| **Version** | Reported agent version                                         |
| **Calls**   | Number of tool calls routed through this device from the agent |
| **Active**  | Timestamp of the most recent activity                          |

Use this view to confirm which host a device is running on, which workspace it belongs to, whether its configuration is in a healthy state, and which agents are talking to it.

## Re-Linking

To move a device 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
```