# Connect a Client

> Create one Thalovant connection, send a setup link, and verify the first heartbeat.

Source: https://docs.thalovant.com/manage/connect-a-client/

---
Use this page when you're ready to connect one app, device, browser flow, or Thalovant Voice room client to a hub.

The smooth path is simple: create the connection, open the setup link, let the client pair once, then wait for Dashboard to show the first heartbeat.

Start under Connections with **Add connection**. Pick the connection type first; the hub and access details come after. The setup link lets one client claim its identity, once. For voice, Thalovant Voice's setup page does the pairing for you. Setup links, connection files, and any copied command with a setup link in it are credentials: keep them private.

## Decide These Four Things

Confirm:

- the hub you want this connection to use;
- the type of connection you're creating;
- a name that describes the app, room, device, or purpose;
- whether the client only needs questions, status, or broader access.

If **Add connection** is locked, open [Billing and Plans](/workspace/billing-and-plans/) before changing setup. Limits are separate from pairing problems.

For the Connections list itself — setup material, states, and what each one means — see [Connections](/concepts/clients/).

## Choose the Connection Type

  
    Best for rooms, kiosks, and assistants that listen and speak through 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.
  

## Steps

1. **Open Connections.** Choose **Add connection**.
2. **Choose the type.** Start with Voice client unless another surface clearly fits.
3. **Choose the hub.** Attach the connection to the hub it should use.
4. **Name the connection.** Use a name like `frontdesk-voice`, `demo-chat`, or `lab-device`.
5. **Choose access.** Keep the recommended narrow behavior unless this client needs more.
6. **Create the connection.** Thalovant prepares a secure one-time setup link.
7. **Open setup.** Follow the setup page until it shows connected.

## Voice Setup

For Voice clients, the setup page opens the easiest path for the computer you're using.

| Platform | What the page offers | What happens next |
| --- | --- | --- |
| macOS | Download Thalovant Voice for macOS. | Install the app, then open Thalovant Voice from the setup page. |
| Windows | Download Thalovant Voice for Windows. | Run the setup app, then open Thalovant Voice from the setup page. |
| Linux | Copy the Linux install command. | Paste it in Terminal once to install, pair, and start the voice runtime. |
| SSH-only Linux | Copy the headless command from advanced options. | Paste it over SSH with the setup link included. |

Keep the setup page open while pairing. It refreshes while the client claims the link and waits for the first heartbeat.

For platform-specific install steps, see [Install Thalovant Voice](/manage/install-thalovant-voice/).

## Other Setup Types

Web chat, Developer, and Embedded connections use the same secure setup idea, but the target client owns the final handoff.

1. **Open the setup link** if the target client can claim it directly.
2. **Copy the setup link** when the client, browser surface, or provisioning tool needs it pasted.
3. **Keep the link private.** A setup link can claim one identity and expires.
4. **Create a new link** if the old one expired, was shared, or was already used.

## Connection Files

Most first setups should use the setup link. It avoids manual file handling.

Some developer, embedded, or recovery paths may still ask for a private connection file. Treat that file like a password. Place it only with the client that needs it, and recreate the connection if the file is exposed.

If your team says "config file", they usually mean the private connection file.

SDK and MCP clients also keep private local state for their encrypted connection.
Keep that state between restarts. Give independently running apps or MCP processes
separate connection identities. For code-based setup, see [Identity Files](/developers/identity-files/)
and the [SDK compatibility table](/developers/sdks/#supported-versions).

## If The Link Expired Or Nothing Connected

| Symptom | First check |
| --- | --- |
| Setup link expired | Open Connections, select the connection, and create a new setup link. |
| Nothing opens after clicking Thalovant Voice | Install Thalovant Voice, then use **Open Thalovant Voice** again. |
| Linux command was copied but nothing connected | Paste the full command once in Terminal and keep the setup page open. |
| Client claimed but is not connected | Keep the app running until the first heartbeat arrives. |
| Connection is still offline | Open [Connections](/concepts/clients/) and check hub, state, access, and live status. |
| The client reports a changed server identity | Stop connecting and confirm the change through support. Do not erase the saved trust state to bypass the warning. |
| An older SDK fails to connect | Install a supported release from the SDK guide; an old identity's legacy key does not help. |

  Don't post setup links, copied setup commands, connection files, tokens, or secrets in public support.

## Done When

The connection is ready when:

- the setup link has been claimed by the intended client;
- Thalovant Voice or the target client is running;
- Dashboard shows the expected connection count or status;
- Topology shows the expected live state when live status is available;
- access rules match what this connection should be allowed to do.

## Next Step

After one connection is live, review its access before adding another one.

Review access rules
Install Thalovant Voice