| --- |
| title: Home Assistant Mi Home |
| emoji: 🏠 |
| colorFrom: blue |
| colorTo: green |
| sdk: docker |
| app_port: 7860 |
| suggested_hardware: cpu-basic |
| --- |
| |
| # Home Assistant on Hugging Face Spaces |
|
|
| This Space runs Home Assistant with Xiaomi Miot and the China-region Haier Smart Home custom integrations pre-installed. |
|
|
| ## Required Space secrets |
|
|
| The web interface works without backup secrets, but the free Space disk is ephemeral. |
| For configuration recovery after a Space rebuild, create a private Dataset on the |
| Hugging Face Hub and add these Space secrets: |
|
|
| - `HF_TOKEN`: a token with write access to the private Dataset |
| - `BACKUP_REPO_ID`: Dataset id, for example `your-name/home-assistant-backup` |
|
|
| The startup script restores `homeassistant-latest.tar.gz` when it exists and uploads a |
| new snapshot every 10 minutes. The backup includes Home Assistant's `.storage` folder, |
| so integrations and onboarding state are retained. It excludes the recorder database, |
| logs, cache, and media to keep the backup small. |
|
|
| ## First use |
|
|
| Open the Space at its public URL and complete the Home Assistant onboarding flow. In |
| **Settings -> Devices & services**, add **Xiaomi Miot Auto** and sign in with the Mi |
| Home account. This integration generally requires the Xiaomi cloud region that owns |
| the devices; it does not require the Home Assistant container to be on the same LAN. |
|
|
| Do not put `HF_TOKEN` in this repository or in `README.md`; use Space Settings -> |
| Repository secrets. |
| ## Agent MCP 接入（同一个 Space） |
|
|
| 网页继续使用 Space 的直接应用地址；MCP 地址为该地址后加 /mcp。采用 Streamable HTTP，非旧版 SSE。 |
|
|
| ### 你需要完成的步骤 |
|
|
| 1. 在当前 Home Assistant 中确认配置已备份成功，再上传本项目文件。Dockerfile 已包含米家和海尔智家集成安装命令，无需手动合并。不要上传 .venv、tests、__pycache__ 或任何令牌。 |
| 2. 创建专用于 Agent 的 Home Assistant 用户，以该用户登录，进入个人资料 → 长期访问令牌，生成令牌。非管理员用户权限仍可能涵盖大量设备；本项目按要求不设置设备或服务白名单。 |
| 3. 在 Space Settings → Variables and secrets → Secrets 中设置 HA_TOKEN 为该长期令牌，MCP_API_KEY 为你生成的随机密钥（建议至少 32 字节随机值）。密钥不要包含换行。保留 HF_TOKEN 与 BACKUP_REPO_ID。可以先部署再创建 HA 令牌；未配置密钥时 MCP 默认拒绝请求，网页仍可使用。 |
| 4. 等待重新构建完成，再在 Agent 中添加远程 MCP，URL 为 https://你的实际应用域名.hf.space/mcp，传输方式 Streamable HTTP，Header 为 Authorization: Bearer 你的MCP_API_KEY。Agent 不需要 HA_TOKEN。 |
| 5. 使用 Agent 的连接测试，然后先调用 list_entities 或 list_services，再控制设备。 |
| |
| 通用配置示例（具体字段取决于 Agent 平台）： |
| |
| ```json |
| { |
| "mcpServers": { |
| "home-assistant": { |
| "url": "https://YOUR-SPACE.hf.space/mcp", |
| "headers": {"Authorization": "Bearer YOUR_MCP_API_KEY"} |
| } |
| } |
| } |
| ``` |
| |
| 可用工具：list_entities(domain 可选)、get_entity_state(entity_id)、list_services()、call_service(domain, service, service_data)。call_service 可以调用该 HA 用户有权执行的服务，包括自动化与脚本；没有实体白名单。它不提供任意路径的 HTTP 代理。服务失败会返回工具错误，不返回 HA 令牌。 |
|
|
| MCP 采用独立 Bearer 密钥，不实现 OAuth；Agent 必须支持自定义 Authorization header。如果仅支持 OAuth 自动登录或旧版 HTTP+SSE，此配置不能直接接入。公开 Space 使用应用直接域名；私有 Space 还有 Hugging Face 平台鉴权，不能仅靠 MCP 密钥访问。 |
|
|
| ### 运行与配置迁移 |
|
|
| Nginx 对外监听 7860；HA 改为内部 8123；MCP 仅监听 127.0.0.1:8000。Nginx 支持 HA WebSocket 和 MCP 请求转发。启动时修改 configuration.yaml 中 inline http 配置的端口与代理信任列表，保留其他 YAML，包括 !include；http: !include 形式需要先手工改为内联映射。代理信任列表改为 loopback 和 10.0.0.0/8。 |
|
|
| 首次无快照会继续初始化；Hub 恢复遇到权限或网络错误时停止，防止新空配置覆盖原备份。首次定时备份在启动约 60 秒后，此后每 10 分钟，正常停止时会尝试最后一次备份。强制终止仍可能丢失未上传配置。免费 Space 休眠时 MCP 和 HA 均不可用。 |
|
|
| 排查：401 表示 MCP 密钥未匹配；503 表示 MCP_API_KEY 未配置；工具报 HA HTTP 401 表示 HA_TOKEN 无效；工具报连接错误或代理 502 可能是 HA 尚未就绪。浏览器直接打开 /mcp 没带鉴权时返回 401 属正常现象。 |
| |
| ## 直接上传文件到 Space |
| |
| 一次提交上传以下文件，保留相对路径，不需要部署压缩包： |
| |
| ```text |
| Dockerfile |
| README.md |
| .dockerignore |
| nginx.conf |
| mcp-proxy.conf |
| mcp_server/requirements.txt |
| mcp_server/server.py |
| scripts/start-homeassistant |
| scripts/run-space.py |
| scripts/backup-homeassistant.py |
| ``` |
| |
| 在 Space 的 Files 页面通过 Add file → Upload files 上传；请核对 scripts 与 mcp_server 下的文件未被放在仓库根目录。所有文件准备好后在同一次提交中保存，Space 将自动重新构建。不要上传 .venv、tests、__pycache__、.pytest_cache、.env 或旧压缩包。 |
| |
| 构建时安装海尔智家（sfairy/ha_haier），启动脚本会将镜像中缺少的集成复制到配置目录的 custom_components 中。启动后进入 设置 → 设备与服务 → 添加集成 → 搜索海尔智家，使用中国区海尔智家账号登录。已经恢复的同名集成目录会保留，不会强制覆盖其代码或账号配置。 |
| |
