Quick start

Open the panel and launch the guided setup

Open the ATM panel from your Home Assistant sidebar. On the Tokens tab, start the guided setup ("Connect your first AI agent"). The wizard takes you from an empty token to a working agent without leaving the panel.

Pick a persona

A persona is a named preset that sets every capability at once: what the agent may read, what it may control, and what needs your approval. New user is preselected and is a safe starting point. It lets the agent read your home and control the devices you grant, while locks, alarms, and covers ask for your confirmation.

Choosing a persona modifies the entire capability set, not just a label; you can fine-tune any single capability later. The personas are described on Capabilities.

Name the test token

The wizard suggests test_token so its purpose is obvious; change it if you like, and set an optional expiry. Name and expiry are fixed once the token is created, so if you want different ones, set them here.

Grant access to one device

The wizard highlights your light domain. Expand it, find a light you can physically see, and click the W button on that row to grant full read and write access; its badge changes to "WRITE". Granting one device is enough to prove the connection; you can grant more later from the token's detail page.

Choose how to connect

You can chat with your agent entirely inside Home Assistant using an API key or local hostname from your model provider, or connect an external app instead. Pick whichever fits:

Set up your model provider

Pick a provider you have already added, or add a new one: choose from the dropdown and click Add new provider…. Paste an API key (or, for a local Ollama server, its URL) and click Validate. Validating only tests the connection and lists its models; nothing is saved until you continue. Once validated, pick a default model.

Try it

Click Try now. The wizard opens the Agent Chat window with your new token and the provider and model you just set up already selected, and a test question typed in for you: "How many lights are in my home?" Press Send. The wizard closes as soon as you send your first prompt, so you land in a normal chat with your new agent.

Connect your agent

The wizard shows a ready-to-paste command for your agent, plus the raw token value; both are shown once here.

Claude Code, for example, is a single command line; substitute your Home Assistant address. Other clients (Cursor, Codex, Gemini CLI, and any MCP-capable tool) connect the same way with their own command or config; the panel shows the exact form per agent, and so does Connect an AI client. If you are not ready to connect an agent yet, Connect later skips straight to the end; the token is already created and waiting on the token page.

Run a test

Ask your agent to do something simple, like "List my Home Assistant lights". The moment it calls ATM, the wizard detects the connection and confirms it. That is the whole loop: a scoped token, connected and verified.