gethome：本地优先的智能家居中枢，内置 AI

gethome hub

你家里的本地大脑。

Matter、Zigbee 和 MQTT 设备汇聚于一个应用。一个可以与之对话的助手，以及通过描述就能写出的规则。它运行在家中的一台小型计算机上，走你自己的 Wi-Fi——用你自己的 AI key，无需云账户。

开始使用 · 功能 · 硬件 · 文档 · gethome.me

hub 所栖身的应用：gethome for iPhone，在 App Store 免费提供。

什么是 hub？

大多数智能家居设备归属于某个账户：把一盏灯与一部手机配对，它就只响应那部手机，不响应其他任何设备。hub 把这一切反过来。它是你架子上的一台小盒子，拥有你的设备，因此你邀请的每个人——各自拥有自己的角色——看到的是同一个家，而且即使所有手机都不在家，你的规则仍会继续运行。一个 hub 就是一个家。

无需创建账户。关于你家的任何信息都不会离开你的网络，除非你给 hub 一个 AI key——而且即便如此，也只发送你所用 AI 功能所需的内容（什么去哪里）。

一句话：你的设备与 hub 通信，你的手机通过你自己的 Wi-Fi 与 hub 通信。

        flowchart TB
    APPS["gethome apps<br/>iPhone · Mac"] <--> HUB["gethome hub<br/>at home"]
    AI["Optional AI<br/>on your own key"] <-.-> HUB
    HUB <--> DEV["Your devices<br/>Matter · Zigbee · MQTT"]
      

功能

• 所有设备，一个应用。Matter 设备、Zigbee 设备（通过 Zigbee2MQTT 和 USB 棒）以及你自己的 MQTT 硬件都说同一种带类型的 schema——16 种设备共 27 项能力——因此每个设备都能获得贴合自身的控制项。→ Zigbee · Matter · the schema

• 向房子提问。助手回答关于你家的问题，操作你的设备，触发你的场景——打字或语音皆可。它运行在你自己的 Anthropic 或 OpenAI key 上；语音版本需要 OpenAI key。→ The assistant

• 用大白话写规则。描述你想要什么，agent 就会写出规则，以流程图形式回显给你，并保存为关闭状态，直到你开启。场景就是可以触发的规则。规则完全不需要 AI key 也能持续运行。→ Automations

• 它从未见过的设备。配对一个 hub 不认识的 Zigbee 设备，agent 会推断出它是什么，从而让它获得真正的控制项，而不是一块空白磁贴。这需要你的 AI key；没有 key 时设备仍会出现，并标记为 needs review。→ AI device recognition

• 全家人的家。用短期有效的邀请码邀请家人。Owner、Member 和 Guest 为内置角色，你也可以添加自己的角色，同一个人可以在第二台设备上以自己的身份登录。→ Roles and sharing

• 发生了什么，何时发生。温度、湿度、空气质量和功率以五分钟为步长保留一周，活动流显示对家提出了什么请求，以及由谁提出。→ History

• 构建你自己的。任何能通过 MQTT 发布 JSON 的东西都可以成为设备，无需 hub 侧代码。你自己的脚本、仪表盘和 AI agent 使用 hub 的本地 REST 和 WebSocket API，配合 API key——权限收窄到你授予的范围，一键即可收回。→ Building on a hub · Agent skills · The MQTT convention · The API

• 默认私密。没有云账户，你的 AI key 留在 hub 上。→ Private by design

另外：用你的 OpenAI key 在 hub 上绘制设备的 AI 肖像，并由家中的每个人共享（portraits）——以及你的房间图片，从几张照片绘制成等轴测剖视图，每台设备都标在它所在的位置（room pictures）。

gethome 家族

• gethome hub（本仓库）——大脑：与你的设备通信，运行你的规则和 agent，并为你的应用提供服务。公开，今天即可安装——见 Get started。

• gethome for iPhone——日常应用：房间和设备、助手、规则、历史和小组件。在 App Store 免费。

• gethome studio for Mac——引导式设置：准备 SD 卡或在你的网络上查找 Pi，安装并认领 hub，并保持其更新——然后显示 broker 的实时流量、设备 schema 库和 AI 的运行日志。我们推荐的 hub 设置方式——从 gethome.me 下载。

• gethome.me——网站：变更日志、隐私政策和条款。

Get started

三步：准备一台小型计算机，在其上安装 hub，然后打开应用。

1. 准备硬件

• 一台运行 64 位 Linux 的小型计算机，例如 Raspberry Pi。→ Choosing hardware 2 GB 或更多内存可同时运行 Matter 和 Zigbee，永远不必二选一。1 GB 或更少默认一次运行一个 radio。你可以将两者都打开，在 Zigbee 网络较小时可以正常工作——随着该网络增长，hub 会交还一个 radio 并说明情况。

• 2 GB 或更多内存可同时运行 Matter 和 Zigbee，永远不必二选一。

• 1 GB 或更少默认一次运行一个 radio。你可以将两者都打开，在 Zigbee 网络较小时可以正常工作——随着该网络增长，hub 会交还一个 radio 并说明情况。

• 为其卡准备 Raspberry Pi OS Lite（64 位）。是 Lite，不是 Raspberry Pi Imager 首先显示的桌面版：它在下一层，位于 Raspberry Pi OS (other) 下。

• 一个 USB Zigbee 棒，如果你想要 Zigbee。我们基于 SONOFF ZBDongle-E 开发，新的时候需要一分钟的固件更新。没有棒，你会得到 Matter、Wi-Fi 和 MQTT 设备。

2. 安装 hub

选择一种方式。两者运行相同的安装程序。

简单方式：gethome studio（推荐）

在 macOS 14 或更高版本的 Mac 上，下载 gethome studio 并按照它操作。它准备 SD 卡或查找已在你的网络上的 Pi，安装 hub 并在出现任何问题时告诉你，然后为你认领它——无需终端，也无需输入配对码。之后它会显示 iPhone 应用不显示的内容：broker 的实时流量、设备 schema 库以及每次 AI 运行及其成本。

手动，用一条命令

没有 Mac，或者更喜欢终端？

• 用 Raspberry Pi Imager 将 Raspberry Pi OS Lite 写入卡，并在写入时打开 SSH。

• 启动 Pi 并登录。

• 运行：curl -fsSL https://raw.githubusercontent.com/gethome-inc/gethome-hub/main/deploy/install.sh | bash

        curl -fsSL https://raw.githubusercontent.com/gethome-inc/gethome-hub/main/deploy/install.sh | bash
      

它会为你的机器下载预构建的 hub，安装 Node.js 22 和 Mosquitto，设置一切以便断电后自行恢复，自行识别 Zigbee 棒并打印配对码——你将在第 3 步中使用它。→ 完整安装指南

3. 获取应用

安装 gethome for iPhone，在 App Store 免费。它会在你的 Wi-Fi 上找到 hub。

• 手动安装的？在应用中使用其配对码认领 hub。谁先认领它，谁就成为其所有者，所有者邀请其他所有人。

• 由 gethome studio 设置的？hub 已经是你的了——studio 已将其认领为你的 Mac。在 studio 的 People 标签页中，在你自己的行上按 Add device，然后输入它在应用中显示的代码：你的 iPhone 以你的身份加入，而不是作为新的人。

在 hub 上获取 shell

本页所有在 hub 上运行的内容都需要先登录：

        ssh <user>@<address>
      

<user> 是你在 Raspberry Pi Imager 中设置的账户（除非你改过，否则是 pi）。<address> 是 Pi 的 IP 或它的 <hostname>.local——也就是应用为 hub 显示的那个主机，不带 :8420，那是 API 而不是 SSH。

如果 hub 是由 gethome studio 设置的，它从未向你索取过该密码——它改为在 Pi 上授权自己的密钥——所以密钥通常是最短的进入方式，而在卡片安装上，它可能还是你唯一仍然知道的：

        ssh -i "$HOME/Library/Application Support/gethome-studio/id_ed25519_gethome" [email protected]
      

引号是必需的：路径中包含一个空格。请使用 "$HOME/…" 而不是 '~/…'——引号内的波浪号不会被展开，ssh 会报告一个不存在的密钥。

常用命令

        sudo gethome-hubctl status          # every service, and what the API says
sudo gethome-hubctl logs 100
sudo gethome-hubctl pairing-code    # the code, until the hub is claimed
sudo gethome-hubctl update          # install the latest build (`rollback` goes back)
      

API 在 http://<hub>:8420/api/v1/hub 应答。更新会保留正在运行的构建，直到新构建通过健康检查；如果未通过，它会自行回退——可以从命令行，也可以从应用（Owners 和 Members 均可）。→ 安装和运行 hub

设计上保护隐私

• 没有云账户、中继或隧道。hub 不会通过你的路由器开放任何东西，你的家只存在于它自己卡片上的一个文件中。不要转发 8420（API）或 1883（MQTT）端口——两者都是为你的家庭网络准备的明文连接，而你的路由器就是边界。

• 你的 AI 密钥加密后留在 hub 上，API 永远不会返回它——甚至不会返回给你的手机。AI 是可选的，每个功能发送什么都有书面记录。

• 除三个请求外，每个请求都需要令牌或 API 密钥（hub 的公开描述、认领，以及 hub 向已经持有密钥的应用证明自身身份），并且 hub 会拒绝任何发往公共域名的请求，这可以阻止网页通过你的浏览器访问它。

• 安装程序会根据已发布的校验和检查其下载内容，如果任何内容不匹配，就不会动你正在运行的 hub。

→ 隐私和网络安全，包括一份简短、诚实的清单，说明哪些内容确实会离开 hub。

须知

• 目前仅限你自己的 Wi-Fi。从外部控制家庭的功能尚未构建——中继已列入计划。你外出时，你的规则会继续运行。

• Zigbee 需要 USB 棒。没有它：Matter、Wi-Fi 和 MQTT。

• AI 功能需要你自己的 Anthropic 或 OpenAI 密钥。没有密钥时 hub 也能工作，无法归类的设备会被标记为 needs review。

• 在 1 GB 或更少内存上，默认一次只运行一个无线电——代价是什么。

用 AI agent 构建

两个 agent 技能可以教 Claude Code、Codex、Cursor 以及其他读取 Agent Skills 的编码 agent 在 hub 上构建，当任务适合时，agent 会自行选择正确的那一个：

• gethome-hub-api 用于使用你家的软件——脚本、仪表盘、桥接、你自己的 agent——通过 API 和 API 密钥。

• gethome-mqtt-device 用于本身就是设备的硬件——ESPHome、Arduino、MicroPython 或你自己板子上的 Python——通过 MQTT 加入。

        npx skills add gethome-inc/gethome-hub
      

这需要 Node.js，且不需要本仓库的副本：它会询问要为你的哪些 agent 安装，只复制两个技能文件夹，其他内容不会留在你的机器上。对于 API 那个技能，请创建一个 API 密钥，并通过其环境变量交给 agent，绝不要在对话中传递。→ 技能 · 在 hub 上构建

文档

• 选择硬件——买什么，以及为什么内存决定一切

• 安装和运行 hub——安装、更新、回滚

• 隐私和网络安全

• Zigbee · Matter · MQTT 用于你自己的硬件

• 自动化 · 助手 · AI 设备识别 · 设备画像

• 在 hub 上构建——API 密钥和你自己的软件，以及用于 Claude Code、Codex 等的 agent 技能

• API · 设备 schema · 架构 · gethome 系列

面向开发者

        cp .env.example .env
npm install
npm run dev                # tsx watch
npm test                   # vitest — 无需任何服务
      

Node.js ≥ 22。没有云端：一切都从这个仓库运行。hub 仅部署在 Linux 上，但在 macOS 上开发和测试没有问题——测试套件不需要无线电硬件，数据库保存在临时文件中。HUB_TEST_MQTT=1 npm test 会增加端到端的 broker 往返测试（需要 Mosquitto）。修改代码前请阅读 CLAUDE.md（工程指南），以及 Architecture（模块地图）。

许可证

• 源码可见。代码以 PolyForm Noncommercial License 1.0.0 公开发布：可阅读、可修改、可分享。

• 个人及非商业用途免费——你的家庭、业余项目、评估、研究。

• 商业部署——酒店、物业管理、付费安装——需要单独的许可证：见 COMMERCIAL-LICENSE.md。

这是源码可见许可证，不是 OSI 开源许可证：开源定义不允许限制商业使用。gethome.me 上的使用条款和隐私政策涵盖 hub 以及 gethome 系列应用；就代码本身而言，以本许可证为准。