ATM v2.2.0

Advanced Token Management (ATM) v2.2

The leanest and most capable way to connect Home Assistant to an AI agent

ATM replaces your MCP server with fine-grained, per-token access control over Home Assistant, considerable cost savings, and a per-entity safety layer. Each AI client gets its own scoped token, and everything runs inside HA, even the chat window: no extra container, no cloud, no external process.

Security

Generate as many tokens as you need, each with its own entity permissions, capabilities, and rate limits. Set an expiry, review the audit log, rotate tokens, and revoke any token instantly. You can require manual approval before a change is applied, and config changes can be rolled back. You never need a long-lived access token (LLAT).

How it compares

ATM was road-tested against the built-in and community MCP servers. Frontier models and local model run against one synthetic home, the same tasks. ATM was the cheapest per completed task and the most successful. With MESA enforced, it protected 100% of off-limits devices while completing 100% of the legitimate work; every server without MESA still toggled 84-90% of the things it was told never to touch. On cost per completed task, ATM came in nearly 6x cheaper than a well known MCP server. Full report.

Install

Via HACS (custom repository):

1. HACS > Integrations > top-right menu > Custom repositories.
2. Add https://github.com/sfox38/ATM, category Integration.
3. Install ATM, then restart Home Assistant.
4. Settings > Devices & services > Add integration, search Advanced Token Management, then open the ATM panel. The Quick start takes it from there.

Manual: copy custom_components/atm into your HA config under custom_components/atm and restart.

Requirements

• Home Assistant 2024.5.0 or later.
• No Python dependencies beyond what Home Assistant ships. One ATM instance per Home Assistant.

Links

• Documentation: https://sfox38.github.io/ATM/
• Quick start: https://sfox38.github.io/ATM/quickstart.html
• Road test report: https://sfox38.github.io/atm-roadtest/
• MESA: https://github.com/sfox38/mesa-core
• Issues: https://github.com/sfox38/ATM/issues

On how ATM was built

ATM is open source and ships with a comprehensive test suite. AI was used in its development, and you are invited to test and review it yourself.

Changelog

The complete release history is on the GitHub releases page. Recent changes:

2.2.0

• New: Bundled mesa-core updated to 1.2.0
• New: Agent Chat, our recommended way to use ATM. Instead of using an external client, you can now talk to Home Assistant from a floating chat window. ATM runs the agent itself, on a token you choose, so every capability gate, per-entity MESA rule, approval, and audit entry applies exactly as it would for any external MCP client.
• New: use ATM with Home Assistant's own Assist and voice. You can now bind an ATM token to Home Assistant's native assistant so a voice or chat conversation runs through that token's scope, MESA safety, approvals, and audit. A least-privilege token (for example the Voice Assistant persona) is recommended. A Confirm-gated action becomes queued for approval in the ATM panel, since voice has no inline Approve button.
• New: ATM as a Home Assistant conversation agent (self-contained voice). The option above hands ATM's tools to a model supplied by a separate integration (OpenAI, Anthropic, Ollama, and so on). ATM can register itself directly as a conversation agent so "ATM" appears in Settings > Voice assistants and runs its own model, an existing Agent Chat provider account, on a token's scope, with no separate integration. ATM can then set up the assistant for you in one click (it creates an Assist assistant pointed at ATM). Confirm-gated actions are queued for approval in the ATM panel (voice has no inline Approve button).
• New: ATM as a Home Assistant AI Task entity. Home Assistant's AI Task lets automations, scripts, and dashboards generate text or structured data with an AI model (the ai_task.generate_data action). ATM can now provide that entity itself, and it runs ATM's own model on the token's scope, with the same per-token permissions, MESA safety, approvals, and audit as the rest of ATM.
• New: mesa_get_profile can include an entity's "semantic moments", the purpose-specific triggers and conditions Home Assistant 2026.7 introduced (e.g. a lock's "locked" trigger), so an agent reading a MESA profile also sees what automation moments the entity offers. Pass include_semantic_moments: true; the list is read live from Home Assistant, is informational only, and is simply omitted on older Home Assistant versions. For moments whose config shape is non-obvious (such as a numeric-threshold crossing), each moment also includes a ready-to-adapt example config, so an agent can copy the exact automation trigger or condition rather than reverse-engineering it. The connection primer tells agents that can author automations to call it on the trigger or condition entity before building the automation.
• New: MESA advisory leases. Two new tools, mesa_request_lease and mesa_release_lease, let an agent announce "I am operating these entities for the next few seconds" (30-second cap) so MESA-aware components can coordinate. A lease grants no authority (every action stays gated by scope, capabilities, and MESA), covers only entities the token could already control, is denied for entities under protected or critical automation control, and lease endings fire an atm_mesa_lease_expired event you can automate on.
• New: MESA profile export and import. Two icon buttons next to the MESA tab's refresh control download your entire MESA profile set as one JSON file (the standard MESA archive format, so it doubles as a backup and transfers to any other MESA-aware server) and import one back. Both confirm first; importing validates every profile, reports anything invalid without writing it, and by default never touches an existing profile. A "Replace existing profiles" checkbox switches to overwrite mode behind a clearly destructive confirm.
• New: the on-boarding wizard now offers Agent Chat as its primary client - external clients are no longer required. After granting access to one device, a new "Choose how to connect" step lets you pick chatting inside Home Assistant or connecting an external app. Choosing Agent Chat walks you through adding a model provider account right there in the wizard, then a highlighted "Try now" opens the Agent Chat window with your new token and provider already selected and a test prompt typed in for you.
• New: Include-graph-aware YAML authoring. The automation, script, and scene tools now follow configuration.yaml's !include / !include_dir_* layout to the correct leaf file and edit only the target entry's lines, preserving comments, formatting, and !secret references everywhere else, instead of refusing whenever an include appeared. Creates route by include flavor (append for plain !include, a new file per entry for directory includes); every write is re-parse-verified before it lands, and anything ambiguous (duplicate ids, packages/inline config, multiple create targets) refuses rather than guesses. Even HA's own UI editor still cannot edit split configurations at all.
• New: per-token MCP server names. The connect instructions now derive the client-side server name from the token's name (atm-<token-name>) instead of one shared name, so you can keep one client entry per token and switch tokens by toggling which entry is enabled in your MCP client, no more clearing auth and retyping. Enable only one atm-* entry at a time.
• New: token settings presets (experimental, off by default). A token can save named snapshots of its full configuration (capabilities, permissions, rate limits, pass-through) and switch between them from its detail view. Turning the setting on saves every token's current settings as its first preset; switching first saves your unsaved changes into the outgoing preset (the dialog shows exactly what), and applying the active preset reverts to its saved state, so nothing is ever lost silently. Switching is admin-only by design.
• New: inline "wait for approval" per-token setting. When a Confirm-gated action is queued, ATM now holds the response open for a short window so that if you approve within it, the agent gets the result in the same call with no second round-trip; if you do not decide in time it falls back to the immediate "pending approval" reply and the agent carries on. On by default at 60 seconds, adjustable per token from 30 to 180 seconds in the token's detail view. Agents that run unattended (no human watching) can be switched to the return-immediately behavior via the admin API.
• New: Zigbee management. Agents can now see radio-network health and, when granted, manage the Zigbee network. Two read tools under the diagnostics capability (get_radio_network for channel, coordinator, and join-window state; get_radio_device for one device's signal quality, availability, and mesh neighbors) and three write tools under a new "Radio management" capability (permit_zigbee_join to open or close the pairing window, reconfigure_zigbee_device to re-interview a misbehaving device, remove_zigbee_device to drop one from the network), all Confirm-eligible. Works with Zigbee2MQTT and ZHA. Network keys and other credentials never appear in any response; device writes require write access to the device'...

ATM v2.0

ATM v2.0 : The leanest and most capable way to connect Home Assistant to an AI agent

ATM replaces your MCP server with fine-grained, per-token access control over Home Assistant, considerable cost savings, and a per-entity safety layer. Each AI client gets its own scoped token, and everything runs inside HA: no extra container, no cloud, no external process.

What's New (highlights)

• Getting-started wizard: Create a token, pick a role, scope it, and get the exact copy-paste config for your client (Claude Code, Cursor, Codex/ChatGPT, Gemini, and others). The wizard waits and confirms when the agent is connected. You go from a new token to a working agent in minutes.
• Personas: One-click presets that pre-scope a token to a role (read-only, voice assistant, automation builder, dashboard designer, maintenance, power user, home admin, and more), then fine-tune from there.
• Expanded toolset, 86 tools: discovery/read (search, overview, describe area/entity, relationships), authoring (automations, scripts, scenes, helpers, dashboards), traces, system health, history, plus dry-run/what-if previews and config version history with rollback. A token is only ever shown the tools its scope requires, not all 86.
• MESA, a per-entity semantic safety layer: ATM is the first MCP server to integrate mesa-core. Label entities by their nature so a device can be confirm-only or off-limits regardless of what permissions a token is granted.
• Tri-state capabilities: every capability is deny / allow / confirm. "Confirm" holds an action as a pending approval until you review it in the panel.
• Cost efficiency: a scoped token means the agent only sees what you allow, smaller context, lower cost, and fewer ways for things to go wrong.

Security

Generate as many tokens as you need, each with its own entity permissions, capabilities, and rate limits. Set an expiry, review the audit log, rotate tokens, and revoke any token instantly. You can require manual approval before a change is applied, and config changes can be rolled back. You never need a long-lived access token (LLAT).

How it compares

ATM was road-tested against the built-in and community MCP servers. One model (Sonnet 4.6), one synthetic home, the same tasks. ATM was the cheapest per completed task and the most successful. With MESA enforced, it protected 100% of off-limits devices while completing 100% of the legitimate work; every server without MESA still toggled 84-90% of the things it was told never to touch. On cost per completed task, ATM came in nearly 6x cheaper than the community MCP server. Full report.

Install

Via HACS (custom repository):

1. HACS > Integrations > top-right menu > Custom repositories.
2. Add https://github.com/sfox38/ATM, category Integration.
3. Install ATM, then restart Home Assistant.
4. Settings > Devices & services > Add integration, search Advanced Token Management, then open the ATM panel. The Quick start takes it from there.

Manual: copy custom_components/atm into your HA config under custom_components/atm and restart.

Upgrading from 1.x

Storage migrates automatically on first load. Each token's old allow_* booleans are converted to the new cap_* tri-state (deny / allow / confirm), and existing tokens are assigned the custom persona. The migration is idempotent and needs no action. Backing up .storage/atm.json first is recommended.

Requirements

• Home Assistant 2024.5.0 or later.
• No Python dependencies beyond what Home Assistant ships. One ATM instance per Home Assistant.

Links

• Documentation: https://sfox38.github.io/ATM/
• Quick start: https://sfox38.github.io/ATM/quickstart.html
• Road test report: https://sfox38.github.io/atm-roadtest/
• MESA: https://github.com/sfox38/mesa-core
• Issues: https://github.com/sfox38/ATM/issues

On how ATM was built

ATM is open source and ships with a comprehensive test suite. AI was used in its development, and you are invited to test and review it yourself.

ATM v1.1

This release is mostly general code cleanup and documentation improvements. No new features.

Initial release

This is the initial release, check the README.md for release notes for this version

v0.9.5 pre-release

v0.9.5 pre-release:

UI revamp complete, frontend enhancements

v0.9.1 pre-release:

Patched multiple issues and further hardened security. Ready for UI revamp now...

v0.9.0 pre-release caveats:

Things may break. Probably not, but who knows. Always keep a backup.

It is feature complete enough for v1.0 though.

If you encounter anything broken, please submit an issue. Do you have any suggestions? I really appreciate your feedback.

Thanks!

Pre-release v0.9.1

v0.9.1 pre-release:

Patched multiple issues and further hardened security. Ready for UI revamp now...

v0.9.0 pre-release caveats:

Things may break. Probably not, but who knows. Always keep a backup.

It is feature complete enough for v1.0 though.

If you encounter anything broken, please submit an issue. Do you have any suggestions? I really appreciate your feedback.

Thanks!

Pre-release v0.9.0

v0.9.0 pre-release caveats:

Things may break. Probably not, but who knows. Always keep a backup.

It is feature complete enough for v1.0 though.

If you encounter anything broken, please submit an issue. Do you have any suggestions? I really appreciate your feedback.

Thanks!