Connect Home Assistant

Stream your Home Assistant devices into Postern. It is the only source an agent can act on.

Before you start

• A Home Assistant that is up on your own network, and about 5 minutes. Postern connects to it directly. No cloud service, no account.
• Postern installed, with the Console open. Open http://localhost:8787 in a browser on the machine Postern runs on. If that machine has no screen, open the Console over SSH.
• Your password manager open. Home Assistant shows the token once, in step 1, and nothing re-reveals it.
• A Home Assistant account you are willing to lend. The token carries exactly what that user can do, and Postern acts as that user. A sector is one area of your life: finance, mail, calendar, contacts, health, home. An agent you grant home can run any device action here, with no confirmation for each one.

1. Create a token in Home Assistant

   In Home Assistant, click your own name at the very bottom of the left sidebar. It sits below Settings and Notifications, with a small round picture beside it. Nothing reads “Profile”.

   Your profile opens on the General tab. Click the other tab, Security. The address now ends /profile/security.

   Scroll to the bottom of that tab. The section headed Long-lived access tokens sits below Change password, Multi-factor authentication modules and Refresh tokens.

   Older Home Assistant versions show no tabs. There the same section sits at the bottom of the profile page — Managing account access.

   Home Assistant shows the token once, at the moment you create it. It keeps no copy of the token string, so nothing re-reveals it and the only remedy is a new token. Open your password manager before you create the token.

   Press Create token, at the bottom right of that section. A dialog opens, headed Create token, with one required field labelled Name*. Type Postern into it. That name is how you tell this token apart from your others in Home Assistant.

   The dialog carries Cancel, which creates nothing, and a second Create token button. That button stays greyed out until the field has something in it.

   Press the dialog’s Create token. Home Assistant replaces the dialog with a screen headed Token created: followed by the name you typed. It warns “Copy your access token. It will not be shown again.” The token sits in a read-only field, too long to read at that width.

   Press Copy, to the right of the field. A message reads “Copied to clipboard”. Paste the token into your password manager. You paste it into the Console in step 3, and again whenever you reconnect.

   A Generate QR code control sits below the token. Postern has no use for it.

   Press Close. Postern appears at the top of the list, with its creation time beside it.

2. Find the address of the Home Assistant machine

   Open Home Assistant in a browser and read the address bar. You need that machine’s numeric address and its port, in the shape of the Console’s own example:

   http://192.168.1.50:8123
   

   8123 is Home Assistant’s own default port. Keep whatever port your address bar shows.

   If the address bar shows a name instead of numbers, open your router’s settings page. Its list of connected devices gives each one a numeric address.

   Postern runs inside its own sandbox, a Docker container. From in there a .local name resolves to nothing. localhost and 127.0.0.1 name the sandbox itself, not your Home Assistant — even when both run on one machine. The Console accepts a wrong address of the right shape without complaint, creates the connection, and the connection never starts. Use the numbers.

   Recommended. Reserve that address for the Home Assistant machine on your router’s settings page. Routers call it a DHCP reservation, a static lease, or an address reservation. Otherwise the address changes weeks later and this connection stops.

3. Paste the address and the token into the Console

   In the Console, go to Sources → Add a source → Home Assistant. The card has two fields.

   Put the address from step 2 into Instance URL. It must start with http:// or https://. Without that the Console answers “That isn’t a URL — your Home Assistant address starts with http:// or https://, e.g. http://192.168.1.50:8123.”

   Put the token from step 1 into Long-lived token. An empty field answers “Paste the long-lived access token you copied from Home Assistant.”

   Press Connect Home Assistant. A message reads “Home Assistant connected.” The Console returns to Sources. The new connection appears under home with the badge Awaiting first push.

   That badge is normal. Home Assistant sends changes the moment they happen, and nothing has arrived yet. There is no schedule to set. Postern rescans its connections every 60 seconds, so the connection comes up within about a minute. No restart, nothing to press. The badge then disappears and the connection reads Instant — connected.

   Unreachable, with “can’t reach source — retrying”: nothing answered at that address. Postern tries again after 5 seconds, then doubles the wait after each failure, up to 60 seconds. A Home Assistant that was not ready yet recovers by itself. A wrong address never does. Error, with “auth failed: invalid token”: Home Assistant refused the token, and Postern will not retry a refused token — Home Assistant throttles repeated sign-in failures. Neither state clears on a timer; a changed address or token is what clears it.

   To correct either value, paste it on this same card. The card reads “Home Assistant is already connected. Connecting again replaces the stored credential — it won’t create a second copy.” Tick Yes — replace the stored credential. and press Reconnect Home Assistant. The next scan restarts the connection within a minute.

Confirm it works

• Console → Sources → the Home Assistant row: under Live stream, the words Stream down are absent.
• The line beneath reads last event with a time on it, not no events yet.
• Entities cached shows a number above 0.
• Change a light or a switch in Home Assistant. That last event time drops to seconds ago.
• Ask an agent granted home what it can control in your house. It answers with action ids such as home.light.turn_on and home.lock.lock.

If something went wrong

What you see	What to do
Unreachable, can't reach source — retrying	Nothing answered there. Paste the numeric address with http:// in front — never a .local name, localhost or 127.0.0.1 — and press Reconnect Home Assistant.
Error, auth failed: invalid token	Create a new token in Home Assistant, paste it on the same card, and press Reconnect Home Assistant. Take the same path if you lost the token before it reached the Console.
The connection sits at Awaiting first push; or an agent granted home lists no actions; or an action returns home assistant: no live connection for this connection id — nothing was dispatched	The live connection is not up, and Postern sent nothing to your house. Correct the address as in row 1 — the Console accepts a wrong address of the right shape.
An action returns admin/system service not permitted (device/entity control only)	Postern never runs admin or system services. There is nothing to change here. Run that one in Home Assistant yourself.

What you have now

The home sector, for reads and for actions. Any agent you grant home sees your devices’ states, reads the action list, and runs the actions you would run yourself: lights, scenes, switches, scripts, automations and buttons. Postern works out which actions apply to which device, so the list arrives instantly. Home Assistant does not offer that mapping itself.

Postern never runs an admin or system service. An agent that names one gets admin/system service not permitted (device/entity control only) back — the domains and services Postern drops.

Postern grants permission per sector only. A granted sector covers reads and actions together, with no narrower grant and no confirmation step — what a grant covers. Console → The ledger holds a row for every call, invoke_action among them, under that agent’s own name. Postern only ever adds to the record.

Postern sends each action once and never repeats it. A break mid-action returns unknown — not retried — Postern cannot know whether Home Assistant acted. Check the device yourself.

Postern stores the token encrypted on your own machine. It stays exactly as powerful as the Home Assistant user who made it: if that account gains permissions, so does this connection.

To stop it at Home Assistant, go back to Long-lived access tokens on your profile’s Security tab. Every token’s row ends in a trash-can icon, with no words on it. Press the one on the Postern row. The connection then fails at its next check with auth failed: invalid token, and stays in error until you paste a new one.

To stop it at Postern instead, go to Console → Sources → the Home Assistant row. Press Remove token. A confirm step opens, headed Remove the token: “Deletes the long-lived token from the vault. Home stops immediately.” Type Home Assistant into the field labelled “Type Home Assistant to confirm”, then press Remove token again. That second button stays greyed out until the typed name matches exactly, and reads “Working…” while it runs. Cancel leaves the connection as it is. On success the Console reads “Revoked the Home Assistant credential.”

When the connection is down, an agent still reads device states from cache. The action list and every action stop.

Next

Connect an agent

a key in hand and the Console open · a few minutes, plus a restart of the client you connect

Connect Google and Gmail

your own Google Cloud app and one app password · about 20 minutes · weekly re-consent until you publish to production