README.md

metadata

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 平台）：

{
  "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

一次提交上传以下文件，保留相对路径，不需要部署压缩包：

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 中。启动后进入 设置 → 设备与服务 → 添加集成 → 搜索海尔智家，使用中国区海尔智家账号登录。已经恢复的同名集成目录会保留，不会强制覆盖其代码或账号配置。