README.md

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