# Connections

> Understand Thalovant connections, setup links, private files, access choices, and live status.

Source: https://docs.thalovant.com/concepts/clients/

---
A **client** is the app, device, or experience that connects to a hub. In the product, you manage clients from **Connections**.

Clients aren't just names in a list. A client is connected to one hub, has a setup path, and has access rules.

Give each connection a clear name so you can recognize it later in Dashboard, Access rules, and Topology.

Before creating a connection, choose the [hub](/concepts/hubs/) it should use. After creation, review [access rules](/concepts/access-rules/) and [Topology](/concepts/topology/) so the setup is easy to verify.

## What A Client Is

A client is whatever connects to a hub: a phone, a speaker, a browser tab, a script. You manage it under Connections. Each client talks to one hub, claims its identity once through a setup link, and is limited by its access rules. A private connection file exists for advanced and recovery paths. When something's off, look at Clients first, then Dashboard and Topology.

## Connection Types

  
    Best for rooms, kiosks, and assistants that listen and speak with Thalovant Voice.
  
  
    Best for browser conversations without installing a desktop app.
  
  
    Best for CLI, API, diagnostics, automation, or local testing.
  
  
    Best for hardware, firmware, and small-device provisioning.
  

A fifth kind, **Home Assistant**, shows up in the list once you link your home.
You don't make it here: Home Assistant creates it when you [link Home
Assistant](/manage/home-assistant/) from its own Thalovant integration, and it
doesn't count toward your plan's connections.

## Create a Connection

Before creating a connection, choose the hub it should use and decide what the client is for.

1. **Open Connections.** Select **Add connection**.
2. **Choose a type.** Pick Voice, Web chat, Developer, or Embedded.
3. **Choose a hub.** Attach the connection to the hub it should use.
4. **Name the connection.** Use a name that describes the app, device, room, or purpose.
5. **Choose access.** Keep the recommended narrow behavior unless the client clearly needs more.
6. **Open setup.** Use the one-time setup link so the client can claim its identity.

Don't create several clients just to test names. Create one connection, pair it, give it narrow access rules, and confirm it appears where expected.

For a guided task flow, use [Connect a Client](/manage/connect-a-client/).

## Choose the Right Behavior

| Type | Best for | Permission style |
| --- | --- | --- |
| Observer | Clients that only need to check status. | Read-only access. |
| Question client | User-facing experiences that ask normal questions. | Questions allowed, wider control blocked. |
| Skill helper | Clients that help Thalovant see available skills. | Skill sharing plus only the small reads it needs. |

## Setup Links

After creating a connection, Thalovant prepares a setup link. That link can be used once and expires.

For Thalovant Voice, the setup page can download the app, open it, and wait for the first heartbeat. On Linux, it can copy a single command that installs, pairs, and starts the voice runtime.

For Web chat, Developer, and Embedded connections, open or copy the setup link into the target client or provisioning tool.

If a setup link expires, is shared, or was already used, create a new setup link from the connection actions.

## Connection Files

Most first setups should use the setup link. Some developer, embedded, or recovery paths may still need a private connection file.

If you're asking "where is my config file?", start with the client record. Some teams say config file when they mean the private connection file.

For security, Thalovant may ask for two-step sign-in or a recovery code before showing the file. First-time setup may offer the file right away so you can finish connecting the client.

:::caution[Keep setup material private]
Treat setup links, copied setup commands, and private connection files like passwords. Store them only where the client needs them, restrict local `_identity.json` files with `chmod 600` on Linux and macOS, and recreate the connection if they are exposed.
:::

## Client vs Setup Material

The **client** is what you manage in Thalovant. The **setup link** or **connection file** is what the app, device, or tool uses to pair.

If setup material is lost or exposed, don't just rename the client. Create a new setup link, pause access, quarantine the identity when review is recommended, lock it when permitted, or recreate the client when a private file may have been exposed.

## Access and Control

Client settings can allow broader actions:

- **Broadcast** lets the client send wider messages.
- **Escalate** lets it ask for higher-level actions.
- **Propagate** lets it pass work along when available.
- **Full control** gives wide control and should be rare.

Most clients should start simple. Add only the extra powers the client truly needs.

## Naming Clients Well

Good client names describe purpose or location, not just a person. Names like `frontdesk-client`, `skill-sync`, or `kiosk-reader` are easier to recognize than `test-1` or `main`.

When a client shows stale or warning state later, a clear name helps you know which app, device, or service needs attention.

## Scanning The Setup Code

Setting a phone up from another screen? Scan the QR code with the phone's
camera or the app's own scanner — it opens the same private setup link. The
code keeps a light background in both themes so it stays scannable.

If scanning is awkward, use the link instead. Treat the code exactly like the
link: private, and used before it expires.

## What Each State Means

| State | What to check first |
| --- | --- |
| Waiting for setup | Open the setup link on the device you meant to pair. |
| Claimed but not connected | Leave the app running until the first heartbeat arrives. |
| Offline | Confirm the app or device is still running. |
| Stale | Refresh, then check whether the client has stopped sending activity. |
| Review identity | Confirm the device is expected. Quarantine and rotate if it looks old or unfamiliar. |
| Missing from Topology | Confirm the client exists, is active, and points at the hub you think it does. |

## Presence and State

The Connections page shows status, type, access rules, identity security, and last activity. A live dot means the client is connected now. Stale or missing means Thalovant hasn't received a fresh update for that client.

**Review identity** means the client identity hasn't reported presence for the review window. Confirm the app, device, or service is still expected. If the dashboard recommends quarantine, use **Quarantine identity**, then rotate or recreate the identity before restoring access.

Useful actions include:

- create a setup link;
- get the private connection file when that path is needed;
- edit type and hub choice;
- pause or restore access;
- quarantine stale or suspicious identity material;
- lock or unlock access when permitted;
- remove the client when it's no longer needed.

## If the Client Is Not Live

Some teams describe this as **client offline**, **client not connected**, **can't connect**, **setup link expired**, **client missing**, **client disappeared**, **config file missing**, or **connection file missing**. Start with the client record before changing the hub.

If the person says the **device is gone** or **device gone**, still start here. A device usually maps back to a client record, setup link or connection file, and live state.

Check these in order:

1. **Client:** confirm it's active and attached to the expected hub.
2. **Setup:** create a fresh setup link if the link expired, was used, or was shared.
3. **Connection file:** confirm the app or device has the current private file if that path is used.
4. **Access rules:** confirm the client can do what it needs on the hub.
5. **Topology:** check whether the client is connected, stale, missing, or warning.

## Client Is Ready When

A client is ready when:

- its name explains the app, device, or purpose;
- it's attached to the intended hub;
- setup was claimed by the intended client, or the connection file is stored only where the client needs it;
- access rules match the client purpose;
- Dashboard and Topology show the expected state when live status is available.