Hermes family OS · 4 of 6 · setup

Set it up

Eight stages. The commands are verified against v0.19.0 (July 2026); the order is the part people get wrong.

Prereqs: an always-on Linux or macOS box (the machine already running Home Assistant is ideal), Docker installed (member sandboxes depend on it), a Telegram or WhatsApp account for the bot, and API access to at least one model provider — Hermes is model-agnostic (Nous Portal, OpenRouter, OpenAI, or your own endpoint).

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

(Windows: iex (irm https://hermes-agent.nousresearch.com/install.ps1), though for an always-on family box you want the Linux path.) Run hermes once to finish onboarding and connect a model provider. Config lands in ~/.hermes/config.yaml, secrets in ~/.hermes/.env.

hermes profile create household
hermes --profile household

Each profile is a fully separate agent — own config, model, credentials, toolsets, memory, skills, sessions. Everything privileged in this build (Home Assistant token, calendar/Notion MCP servers, Portal browser tools) gets configured in this profile and no other.

hermes --profile household gateway
# lead DMs the bot, receives a one-time code, then on the box:
hermes pairing approve telegram <code>
hermes gateway list

Connect Telegram (or WhatsApp) following the messaging docs — both are confirmed gateway platforms with group-chat support. The pairing dance is the security model: unknown senders get a one-time code, the owner approves it on the box, revocation works the same way. The gateway installs as a background service (systemd/launchd), so it survives reboots. Then add the bot to the family group chat. Do not enable any allow-all option to save time — that switch is checked before pairing and turns your bot into a public one (trap № 1).

hermes profile create sam-agent --clone-from household
hermes --profile sam-agent gateway
# Sam DMs the member bot, gets a code:
hermes pairing approve telegram <code>

Then trim it, in the member profile’s own config:

• Strip credentials from its .env — no HASS_TOKEN, no MCP or Portal keys. Cloning copies config; secrets should never ride along. Verify by asking the member agent to list its tools: no ha_*, no browser_*.
• Trim toolsets to roughly: messaging, memory, todo, file, skills, session_search. No cronjob (one scheduler per house), no delegation, no homeassistant.
• Switch the terminal backend to docker in the terminal section — the hardened container (all capabilities dropped, no-new-privileges, 256-process cap, 512 MB tmpfs) is the boundary for anything a member can trigger. execute_code on the local backend is not sandboxed.
• Set approvals.mode and add approvals.deny fnmatch globs for anything you never want a member profile to run (package managers, network tools, paths outside the vault).
• Fence writes with HERMES_WRITE_SAFE_ROOT pointed at the family vault (stage 6). Hermes’s protected paths already shield ~/.ssh/ and .env files.

Repeat per member who wants a private line. Members who only use the group chat (or aren’t paired at all, like an eight-year-old) need no profile.

# in the household profile's .env:
HASS_TOKEN=<long-lived access token>
HASS_URL=http://homeassistant.local:8123

That’s the whole switch: with HASS_TOKEN set, the ha_list_entities / ha_get_state / ha_list_services / ha_call_service tools enable automatically, and the HA gateway platform can stream state-change events (scope them with platforms.homeassistant.extra’s watch_domains / watch_entities rather than watch_all; cooldown_seconds defaults to 30). Room-by-room build-out, the HA add-on route, and pattern-learning are the smart home plan.

mkdir -p ~/family-vault/members
touch ~/family-vault/groceries.md

The vault is yours, not Hermes’s — a plain directory both profiles’ skills read and write (see architecture). For the calendar and the grocery push, use Hermes’s MCP support (“connect any MCP server”): add a Google Calendar MCP server and a Notion MCP server to the household profile only, with their credentials in its .env. Which specific server implementations are current moves monthly — pick maintained ones and treat them as replaceable parts.

hermes gateway list   # expect: household + one per member profile
hermes cron list      # empty now; the prompts page fills it

Two gateways minimum, each paired to the right humans, member profiles unable to see house credentials. Cron jobs come next — they’re created conversationally in the prompts (the agent has the cronjob tool; jobs land in ~/.hermes/cron/ and are managed with hermes cron list/pause/resume/remove).

8 · Then stop

Resist configuring more tonight. Run stages 1–7, let the morning brief fire once, and tune from evidence. The prompts page is the rest of the build.