Skip to content

ATM v2.0

Choose a tag to compare

View all tags
@sfox38 sfox38 released this 28 Jun 06:03
v2.0.0
2c9231f
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

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

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.

Assets 2
Loading