Transform your Home Assistant configuration with the power of AI
Getting Started • Features • Documentation • Support
Upstream attribution: This is an independent Home Assistant add-on that redistributes and integrates OpenCode, © 2025 opencode, under the MIT License. It is not made by, affiliated with, or endorsed by the OpenCode team or Anomaly. See the third-party notices.
Install OpenCode for the stable channel, or OpenCode Beta to test upcoming changes. See the stable changelog and beta changelog for current versions and bundled component updates.
This is a Home Assistant Supervisor add-on (called an app in newer Home Assistant versions), not a standalone Home Assistant Core/Container integration. It supports amd64 and aarch64/ARM64.
Stable 3.5.1 includes OpenCode 2.3.0, OpenChamber 2.7.2 and HAB 1.8.0. Upgrading an existing installation? Back up first and read the 3.5.1 upgrade notes, including stable history preservation and backup-based rollback. Coming from 2.x? Follow the 2.x upgrade guide.
⚙️ Hardware requirement: x86-64 CPUs need SSE4.2, and the regular build also requires AVX2. SSE4.2 alone may not be sufficient: the documented upstream baseline-package issue can still prevent non-AVX2 CPUs from running OpenCode. ARM64 is unaffected by these x86 requirements. See CPU requirements before installing on older hardware or a VM.
Or add manually
Go to Settings → Apps → Install app → ⋮ → Repositories. On older Home Assistant versions, use Add-ons → Add-on Store instead.
Add: https://github.com/magnusoverli/opencode
Find "OpenCode" in the app/add-on store and click Install.
💡 Prefer the beta channel to try new features early? Install "OpenCode Beta" from the same repository instead — it installs side by side with the stable add-on. See Release channels.
Start the add-on, then click Open Web UI (or use the sidebar entry). By default you'll land in a web terminal.
💡 Prefer a graphical interface? Set Interface (
interface_mode) toopenchamberin the add-on Configuration tab and restart to use the OpenChamber web UI on the same sidebar entry. Both interfaces use the same managed OpenCode V2 backend and conversation history within that channel.
The web terminal opens OpenCode automatically. Enter /connect and follow the
provider's sign-in prompts, then /models to choose a model. In OpenChamber, use its provider/model
settings instead. Anthropic, OpenAI, Google and other cloud or local providers
are supported; credentials, subscriptions and usage charges depend on the provider.
OpenCode and OpenChamber are pinned in the add-on image. Update them through Home Assistant Supervisor, not an upstream in-app updater.
Once connected, ask OpenCode things like:
# Create a new automation
"Create an automation that turns on lights when motion is detected"
# Review your configuration
"Check my configuration.yaml for any issues"
# Add sensors
"Add a template sensor to track my total energy usage"
# Get entity information
"What's the current state of all my lights?"
# Troubleshoot
"Why isn't my bedroom motion sensor triggering automations?"
# Analyze history
"Show me temperature trends for the past 24 hours"
OpenCode brings the OpenCode AI coding agent directly into your Home Assistant instance. Experience intelligent configuration editing through natural language, advanced YAML assistance, and deep integration via the Model Context Protocol (MCP) — with a growing set of features that help it understand your installation, not just configuration syntax in general.
|
Use natural language to modify your Home Assistant configuration. No more searching documentation - just ask! Choose a web terminal with 10 themes or the graphical OpenChamber web UI through Home Assistant Ingress. Both share one backend and history within a channel. Optional LAN frontends require separate authentication and a trusted HTTPS reverse proxy; mapping a port alone is not enough. The OpenCode LAN API also supports device pairing and individual revocation. See LAN setup. Works with Anthropic, OpenAI, Google, other cloud providers and OpenAI-compatible local servers. Available models and authentication methods depend on the bundled runtime and provider. Opt-in PPQ support uses an attested encrypted transport for eligible private models. Configure a PPQ key and explicitly select a private model; enabling it does not switch existing sessions. Account-backed encrypted inference remains unverified. See PPQ setup. Choose Select |
Bundled tools, resources and guided prompts cover state and service calls, history, config validation, calendars, decision notes, updates, ESPHome, Supervisor diagnostics and CLI gateways. Inspect apps by display name, review redacted options and before/after changes, and preview option or lifecycle operations without applying them. Applying a single-use, five-minute plan requires the Sessions start knowing your installation instead of rediscovering it. A generated briefing describes your setup, Home Assistant YAML diagnostics, completions, hover and definitions are available through agent tools, with live diagnostics/completion in OpenChamber's Ingress editor. Whole-file YAML formatting is opt-in. See language assistance. Use Includes the Home Assistant Builder CLI by @balloob for dashboards, registries, helpers, backups and administration. Agents use the authenticated An opt-in, persistent place for your own scripts to run at add-on startup. Scripts run as root; keep customizations in the supported startup hooks directory, not the disposable container filesystem. Connect to Home Assistant's native MCP tools independently of bundled tools. An optional experimental companion also lets HA use OpenCode for Assist conversations and AI data tasks. These are separate integrations; see setup and requirements. |
OpenCode is an open-source AI coding agent that transforms how you interact with your codebase. It understands your files, executes commands, and helps you build and maintain software using natural language.
Think of it as your personal expert developer who:
- 📖 Reads relevant configuration files and inspects live state through tools
- ✏️ Suggests and implements improvements
- 🐛 Helps diagnose bugs and apply approved fixes
- 🚀 Implements new features on request
- 💬 Explains complex configurations in plain English
OpenCode supports cloud providers and local models. Choose a provider and model that support tool calling and fit your hardware, privacy needs and budget:
🔥 Popular Providers (Click to expand)
| Provider | Notes |
|---|---|
| 🧠 Anthropic | Claude models — recommended for configuration work |
| 💎 OpenAI | OpenAI models with supported API-key or subscription sign-in |
| Gemini models | |
| ☁️ AWS Bedrock | Claude, Llama, Mistral, and others via AWS |
| 🔷 Azure OpenAI | Azure-hosted OpenAI models |
| 🐙 GitHub Copilot | GitHub sign-in; requires an eligible Copilot account |
| ⚡ Groq | Ultra-fast inference for open models |
| 🎯 Mistral | Mistral and Codestral models |
| 🦙 Ollama | Local models — see the context-window and tool-profile guidance before choosing hardware |
| 🌐 OpenRouter | Models from multiple providers through a single API |
| 🤝 Together AI | Hosted open-weight models |
| 🔥 Fireworks AI | Fast inference for open models |
| 🚀 xAI | Grok models |
| 💫 DeepSeek | DeepSeek models |
Running models locally? The add-on sends a large tools-and-instructions prompt on every request. Read the context-window and tool-profile guidance first — a small model on modest hardware can take minutes per reply. A smaller MCP tool profile (see Features) is one of the easiest ways to cut that cost.
The add-on does not include a paid model subscription. Upstream may offer free models, but availability, limits and terms can change; do not assume every model offered through OpenCode is free or keyless. Check the provider's current pricing and OpenCode's provider documentation.
For browser-based provider sign-in in OpenChamber, follow the sign-in handoff guide. For a separate local inference server, see the custom-provider examples.
Your prompts and tool results are sent to the selected model provider. Local models need a separately running inference server; the add-on itself is not one.
This add-on has read/write access to your Home Assistant configuration directory.
It also mounts Home Assistant add-on development folders (/addons and /addon_configs) so OpenCode can help with custom add-ons. Treat /addon_configs as sensitive because it may contain configuration data for other add-ons.
The bundled write_config_safe and patch_config_safe MCP tools share a
validation and recovery pipeline. These checks apply to writes through those
tools, not every file write:
- 🔎 Review before applying — preview first, then approve the proposed content. Whole-file writes require the preview's source revision; patches also require its candidate hash. Stale revisions are rejected
- 🔐 Coordinated writes — atomic replacement and a shared writer lock protect cooperating app writers. Unrelated external editors are not covered by an atomic compare-and-swap
- 🔍 HA config validation — after writing, the tool runs HA Core's config check; a failed or unavailable check is not reported as a successful save
- ↩️ Backup and recovery — unique recovery copies and journals are retained in
/homeassistant/.opencode-safe-write-backups/. On failed validation, the tool attempts to restore the original or remove an invalid new file. Onlyrestoredconfirms verified restoration; an uncertain outcome requires inspection. Keep independent backups - 🧪 Jinja2 template pre-validation — checks changed templates through HA's engine where possible; unchanged or runtime-dependent templates can be skipped
- 📋 Deprecation scanning — checks for outdated syntax and cross-checks your instance's HA Repairs warnings
- ✂️ Guardrails against accidental data loss — large deletions (missing list entries, removed top-level keys, or a file shrinking by more than half) are blocked unless explicitly confirmed
- 🏥 HA Repairs integration — surfaces your installation's active deprecation warnings
⚠️ Structural checks — catches missing triggers, actions, and other required fields
Other guardrails and their limits:
- ✅ Direct-edit approval — native file edits and configured shell patterns (
yq -i,sed -i,tee,rm,mv) ask by default. These rules do not detect every possible shell write, and approval does not run safe-write validation. The YAML write tools have no separate managed native edit prompt; agent instructions still require your consent. Supervisor app apply has its own mandatory native permission prompt - 🔒 Sensitive-file read protection — the normal agent's read tool denies
secrets.yaml,.storage/,.cloud/,ssl/,*.key/*.pem, and safe-write recovery files by default. This is not a shell sandbox: allowed shell commands run as container root and can bypass read-tool restrictions. See protection scope - 🔄 Saved is not active — neither YAML write tool reloads Home Assistant. Apply an approved domain reload or restart as appropriate, then verify loading. The
configurationprofile omits service calls, so reload remains a manual step. Editor-API saves can activate automatically; consent must cover that behavior. See editing automations
Additional best practices:
- 💾 Always backup your configuration before significant changes
- 👀 Review changes suggested by the AI before accepting them
- 📝 Use version control (git) when possible for easy rollback
Home Assistant's native llm platform and keyed MCP endpoints are available from
HA 2026.8. The add-on supports several distinct connections:
- Bundled Home Assistant tools (
mcp_enabled) provide the add-on's configuration, validation, diagnostics and administration surface independently of HA's MCP Server. - Home Assistant native tools (
native_ha_mcp_enabled) connect OpenCode to HA's own MCP Server. On HA 2026.10+, enable it under Settings → System → AI → Model Context Protocol; on older versions, add the Model Context Protocol Server integration. Review the add-on's native settings and restart it. - Expose read-only MCP to Home Assistant (
ha_mcp_server_enabled) is an opt-in reverse connection, sharing the add-on's read-only tools with HA. See read-only sharing. - OpenCode Assist (
ha_assist_enabled) is an experimental, default-off companion for HA 2026.10–2026.11 with Supervisor. Enable it and restart the add-on, then restart Home Assistant Core to load the companion and configure the discovered integration. Choose a model and AI tools explicitly. Voice also needs separate speech engines; full supervised voice-pipeline and crash-recovery qualification remain open. See Assist setup.
Native bridge defaults: native tools are on for new installs and use Your
MCP API (/api/mcp); upgrades preserve effective enabled/disabled state and
migrate legacy Assist selections once. home_assistant, assist and custom
selections are available. /api/mcp follows HA's selected APIs and can expand
when Expose all LLM APIs is on. The add-on does not enable or reconfigure HA's
MCP Server. No URL or token needs copying. Review
migration and rollback guidance.
On HA 2026.11, the MCP Server's Read-only setting applies to the configured
/api/mcp endpoint, not independently selected /api/mcp/<ID> endpoints or the
Assist companion's directly selected AI tools. Review the selected API's access
scope; administrator tools are not limited to entities exposed to Assist.
Bundled, native and external MCP connections activate independently. A connected status alone does not prove native tools have loaded: verify a suitable read-only tool. Native tools complement, rather than replace, the bundled safe-write and administration workflows.
Stable and beta have separate histories and settings, but edit the same HA configuration. Only one channel should manage the shared Assist companion; follow the ownership-switch instructions when moving between them.
Comprehensive documentation is available covering all features:
- 📖 Full Add-on Documentation - Complete guide to all features
- 🧪 Beta Documentation - Beta-specific setup and limitations
- 📝 Stable Changelog / Beta Changelog - Version history and updates
Need help? We've got you covered:
|
Upstream OpenCode community; use this repository's issues for add-on problems |
Upstream guides; add-on-specific setup is in our documentation |
Bug reports & feature requests |
On Linux with Bash, Node 24/npm, Python 3, Git, a C compiler (cc), Chrome and
Docker available:
bash scripts/ci-checks.sh beta contracts
bash scripts/ci-checks.sh beta imageUse stable for the stable channel. The contracts command installs the pinned
dependencies, audits them, and runs the channel's tests and root-boundary checks
(using sudo when needed). Set HA_ASSIST_BROWSER_EXECUTABLE for a different
Chrome/Chromium path. The image command explicitly builds boundary-test;
an ordinary Docker build does not run that stage.
Use an LF checkout for Linux builds: hash-checked compatibility files and
fixtures must retain their committed bytes.
CI selects the affected channels. Shared changes exercise both, in independent jobs, so a stable failure does not hide beta results. Contract logs are retained as workflow artifacts; native AMD64/ARM64 image checks retain their build records.
We love contributions! Here's how you can help:
- 🍴 Fork the repository
- 🔧 Create your feature branch (
git checkout -b feature/amazing-feature) - 💾 Commit your changes (
git commit -m 'Add amazing feature') - 📤 Push to the branch (
git push origin feature/amazing-feature) - 🎉 Open a Pull Request
Contributions of all kinds are welcome — feel free to open a PR!
Channels are folders, not branches. Both live on main:
ha_opencode/— the stable channel. Taggedv*, published as the OpenCode add-on.ha_opencode_beta/— the beta channel, for work still soaking. Taggedbeta-v*, published as the OpenCode Beta add-on.
Each folder is a complete add-on with its own Dockerfile and rootfs/, so a
stable release cannot contain something that only exists in beta. Put
experimental work in ha_opencode_beta/; change ha_opencode/ when preparing
a stable fix or promoting validated beta work. Merging does not publish an image;
the release workflows build and publish the tagged channel.
Both add-ons can be installed side by side — they keep separate decision notes
and app storage, but share Home Assistant configuration files and AGENTS.local.md.
Installing the other channel does not transfer conversations or provider sign-ins.
Use different host ports if exposing both channels' LAN frontends, and only one
channel to manage the shared Assist companion.
The devcontainer is the default local development environment. It runs the
add-ons under Home Assistant's official Supervisor development environment. Run
the Start Home Assistant task first, then use the install, rebuild, start,
and log tasks for either ha_opencode or ha_opencode_beta. On a first run, use
Install App followed by Start App; use Rebuild and Start App while
iterating, and run Run App Acceptance after runtime or lifecycle changes. The
install task first registers the app, then builds the working tree over its local
image tag; rebuilds stop the app before replacing that tag. Acceptance traverses
Home Assistant Core's real Ingress route and, for beta, verifies automatic s6
recovery after a sidecar crash. Native amd64 and arm64 boundary checks run in
GitHub Actions; a local emulated arm64 build is not a release gate.
Thank you to everyone who contributes code, reports issues, tests releases or improves the documentation!
View contributors on GitHub. The avatar image is automatically generated from GitHub contributor data by contrib.rocks, not maintained as a separate list in this repository. The stable and beta changelogs also credit reports and suggestions.
This add-on builds on OpenCode, OpenChamber and @balloob's hab CLI, among other open-source projects. See third-party notices for retained license and attribution information.
This is free and unencumbered software released into the public domain - see the UNLICENSE file for details.
This distribution also includes third-party software, including OpenCode. Its copyright notices and license terms are retained in THIRD-PARTY-LICENSES.md and in the add-on image at /usr/share/doc/ha-opencode/NOTICE.
Made with ❤️ for the Home Assistant community