Connections

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 it should use. After creation, review access rules and 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.

Every connection is one client on one hub, with a role and a live status. The row’s actions open, pair, rotate, edit, pause or delete it.

Connection Types

Voice client

Best for rooms, kiosks, and assistants that listen and speak with Thalovant Voice.

Web chat

Best for browser conversations without installing a desktop app.

Developer client

Best for CLI, API, diagnostics, automation, or local testing.

Embedded client

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

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.

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.