# Connectors

> How your hub reaches Home Assistant, Music Assistant and other services in your home through one connection your home opens, and what it can and can't do.

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

---
A **connector** is how your hub reaches a service in your home: Home Assistant for the lights and the locks, Music Assistant for the music. A hub in the cloud can't open a door into your network, so your home opens it instead. A small program or integration at home connects out to the hub, waits, and does what the hub asks. Nothing is opened on your router.

What the hub may ask is written down once, as a short list of verbs for each service: play, pause, set the volume, turn off. The hub's router refuses anything that isn't on the list, sends the rest to your home and to nobody else's, and checks the answer on the way back. This page explains those rules and where they stop.

## What Exists Today

| Service | How it reaches your home | Where it stands |
| --- | --- | --- |
| Home Assistant | The [Home Assistant link](/manage/home-assistant/), an integration you install from HACS. | Available. Version 0.5.0 hands your sentences to Assist, carries structured actions and carries the Music Assistant requests; the music requests need 0.5.0 or later. |
| Music Assistant | The Home Assistant link, [Home media](/music-and-home/home-media/), or a home bridge you run yourself. | See [Through Home Assistant](/music-and-home/music-through-home-assistant/) and [Without Home Assistant](/music-and-home/music-assistant-without-home-assistant/). The bridge program isn't published yet. |
| Jellyfin | [Home media](/music-and-home/home-media/) or a home bridge. | The [Media skill](/concepts/media/) can also call your server directly, on a hub of your own. |
| Plex | Not on a connector. | The Media skill calls your server directly. The platform has no verbs for Plex yet. |

If you run Home Assistant, use its link: it carries the same Music Assistant requests as the bridge. If you run Music Assistant or Jellyfin alone, turn Home media on by voice on a device, or run the bridge yourself.

## How a Request Gets There

1. **The hub works out who spoke.** It reads its own record of the connection: the Thalovant account the device belongs to, and the name the platform gave it. It never trusts what a device says about itself.
2. **The skill makes one structured request.** "Play Adam's Song in the kitchen" becomes a service, a verb (play) and its arguments (a song name, a speaker name).
3. **The router checks it against the service's fixed verbs.** A verb or argument that isn't on the list is refused and nothing is sent. The skill tells you it couldn't.
4. **It goes to your account's connection to that service.** One connection, one delivery. Never to another household's.
5. **Your home does it.** The bridge asks Music Assistant. The Home Assistant integration asks Home Assistant.
6. **The answer comes back and is checked again.** It's a short code and a few plain words, such as a title or a speaker name. The skill says it in the speaker's language.

Home Assistant differs in two ways. Its request also carries the words you said, because Assist reads sentences. And its answer is free text, which the router strips of markup and cuts to a length that can be spoken (600 characters unless the hub is set otherwise) before the speaker says it.

## The Connection Only Dials Out

The bridge or the integration opens the connection to the hub and keeps it open. There is no port to forward, no tunnel and no public address.

A connector connection is not a device. It can send one thing, the answer to a request, and the hub refuses anything else from it: no sentences, no audio, no requests of its own. Nobody else may send the connector messages either, so a device can't ask your Home Assistant anything. The one exception is a device of yours that has [Home media](/music-and-home/home-media/) turned on: it answers for your household on the connection it already has, only for Music Assistant and Jellyfin, and only to a request the hub sent it. The connection has no MQTT credential and doesn't count toward your plan's connections. Only the account that owns it can create it and download its identity file. A children's hub can't take a home bridge connection.

## What the Router Checks

- **Your household only.** The router finds the account that owns the speaking device and picks that account's most recently connected connection for the service. An answer counts once, from that connection, in time. A request never fans out.
- **A fixed set of verbs.** Each service has a closed list, and each verb has arguments with set types and sizes. There is no raw address and no free command. Music is a name searched in your library.
- **Names are words.** A name in a request can't contain `<`, `>` or `://`. A title with a `<3` in it is refused as a request, and cleaned when it comes back in an answer.
- **Answers are rebuilt.** For Music Assistant the service answers with a code from a closed list, and your skill says its own sentence. A service can't put its words, or any markup, into your speakers.
- **Strangers can't ask.** A preview or chat bridge on a public hub is shared by people who aren't the account holder, so it can't reach anyone's home. A connection kind the router doesn't know can't either.
- **Budgets.** Each household has a few requests in flight and a per-minute budget for each kind of request: changing something, reading something, and the sensitive ones below. Each service also has a ceiling for the whole hub. A request over budget is refused as busy. The numbers live in the connector's specification and may change.

## What Stays Home

Each request carries the service, the verb and its arguments, the language, and the number and name of the device that spoke. Home Assistant also gets the words you said.

A request does not carry audio, your account details, your location, anything else you said to the hub, or, for Music Assistant, the sentence itself.

The service tokens stay at home. The bridge keeps your Music Assistant token in a file on its own computer and refuses to start if other people can read that file. Home Assistant keeps its own credentials. Your library, the service's error messages and its addresses never go back to the hub: the answer is a code and a few words.

The direct route is different. If you fill in the Music Assistant skill's server address and token, or the Media skill's, the token is stored as a skill secret on the hub. Prefer the bridge or the Home Assistant link when the hub isn't on your network.

The hub does see each request and its answer, because it's the one that speaks them. On a self-hosted hub that's your machine.

## Sensitive Actions

Locking, unlocking, arming and disarming are sensitive. The router gives them their own, lower per-minute budget.

The Home Assistant integration is stricter. With **Allow locks, alarms, garage doors, gates, valves and sirens** off, which is the default, it doesn't carry these out as structured actions. The sentence goes to Assist as words, and Home Assistant's own exposure rules decide. With it on, a sensitive action runs only when:

- The entity is exposed to Assist.
- The action names exactly one entity. "Unlock the kitchen" does not unlock every lock in the kitchen, and "turn off all the automations" does not disable your automations.

To disarm an alarm panel by voice, the integration needs the alarm code. It keeps the code in its own options, the hub never sends it, and the integration's diagnostics redact it.

The integration also treats sirens, valves and garage, gate, door and window covers as sensitive. The router's separate budget covers only locking, unlocking, arming and disarming.

## Which Devices May Use a Skill

A skill sits in your hub's runtime with one set of settings for everyone who speaks to that hub. On a public hub that includes strangers, so the rules differ by route.

- **Home Assistant link and home bridge.** Each household reaches its own link and nobody else's, so these are the routes for a hub other people use. A device that isn't yours never reaches your home.
- **Server address in the skill's settings** (Music Assistant's server address route, and the Media skill). One address and one token serve every device on the hub. A public hub refuses these settings, and a hub that has them can't be made public. Only the devices you put in **Allowed devices** can use them, and an empty list means nobody.

A skill learns who is speaking from the router's stamp on the sentence, never from the connection's own text. With no stamp, it denies. A device that isn't allowed gets nothing and no error: the skill hands the sentence back, silently, so other skills can answer it, and never contacts your server. A device is listed by the name the console shows (`client-…`) or its ID.

## Where It Stops

- A connector can say something untrue. The specification limits what a service can say, not whether it's true. A bridge that reports "playing" when nothing plays is a bridge that's broken. It can only affect its own household.
- Skills you add are trusted. Any skill in your hub's runtime can ask the router for a verb on behalf of the device that spoke. The router doesn't check which skill asked yet.
- On the server address route, the skill dials the address you give it from your hub's runtime. What that runtime can reach inside Thalovant's network is limited by its network policy, not by the skill. Both skills refuse link-local and metadata addresses and cluster names.
- Not every hub can take a bridge or Home media. A hub for children refuses a home bridge, and so does a hub that scales out or has no router.

## Next Steps

- [Link Home Assistant](/manage/home-assistant/) covers the integration, what the Home skill reaches, and linking from HACS.
- [Music Assistant](/concepts/music-assistant/) covers what you can say and the routes to your server.
- [Media](/concepts/media/) covers Jellyfin and Plex.
- [Clients](/concepts/clients/) explains connections and their states.
