Connections

Connections are the user-facing setup path for clients.

Use the Connections page when you need to add an app, device, room client, browser flow, or developer client to a hub.

On the Free path, Connections focuses on one Thalovant Voice client attached to a public hub. Workspace plans unlock broader client types, owned hubs, and advanced operational views.

Start Here If

• you see Connections in the app and want to know what it owns;
• you need to create or pair a client;
• a setup link expired or was already used;
• a connection is offline, idle, stale, or missing;
• a connection shows Review identity;
• you need the connection file for an advanced or recovery path.

At a Glance

Question	Simple answer
What is a connection?	The setup path that creates or pairs a client.
What is a client?	The identity that exists after a connection is created.
Where do I start?	Choose Add connection from Connections.
What should stay private?	Setup links, copied setup commands, and connection files.
What comes after pairing?	Review permissions, then check Dashboard or Live Map.
What is different on Free?	Start with one voice connection to a public hub.

What Connections Shows

Connection list

The clients created in your workspace or attached to public hubs.

Setup links

One-time links used to pair the intended client.

Connection state

Whether the client is active, idle, disconnected, stale, waiting, or marked for identity review.

Private files

Advanced setup material for clients that cannot use the setup link path.

Create One Connection

1. Open Connections. Choose Add connection.
2. Choose the connection type. Free starts with Voice. Workspace plans can use Web chat, developer, and embedded paths for other surfaces.
3. Choose the hub. Use the public hub or owned hub this client should reach.
4. Name the connection. Pick a name that explains the purpose, such as frontdesk-voice or demo-chat.
5. Create the setup link. Keep it private and use it only on the intended device or app.
6. Wait for the first heartbeat. The client may need a moment after it claims the link.

After It Connects

Read the setup in this order:

1. Connection: client exists and points to the right hub.
2. Permissions: access is narrow and matches the client purpose.
3. Dashboard: counts and attention items look expected.
4. Live Map: the client appears under the hub when live status is available.

Setup Links and Connection Files

Use a setup link for normal first setup. It is the lowest-friction path because it pairs the client without manual file handling.

Some advanced or recovery paths may still use a private connection file. Treat that file like a password. Store it only where the client needs it and recreate the connection if the file is exposed.

On Linux and macOS, local _identity.json files must be private to the current user. Run chmod 600 _identity.json before using an SDK from a laptop or VM.

Caution

Do not post setup links, copied setup commands, connection files, tokens, or secrets in public support.

Common Connection States

State	What to check first
Waiting for setup	Open the setup link on the intended client.
Claimed but not connected	Keep the app running until the first heartbeat appears.
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 or runtime is expected. Quarantine and rotate if the identity is old, missing, or suspicious.
Missing from Live Map	Confirm the client exists, is active, and points to the expected hub.

Connections Look Right When

Connections are healthy when:

• each connection has a readable purpose;
• setup material was used only by the intended client;
• the client is attached to the right hub;
• permissions explain what the client can do;
• Dashboard and Live Map agree with the expected state.

Next Step

Create the connection first, then review permissions.

Connect a clientReview permissions