Getting started
Household overview
Household runs assistant bots with coding harnesses such as Claude Code or Codex. Talk to each bot in a messenger, with its own VM, network access and credentials under your control.
A daemon, house, runs on your Mac or Linux machine. It starts each bot in its own microVM, connects it to a messenger (e.g. Telegram) and stands between the bot and the internet. Each bot answers in its own thread and keeps its files and memory between conversations.
Core concepts
| Concept | Description |
|---|---|
| Workspace | A group of bots sharing an allowlist, secrets, channels and owners. |
| Channel | A workspace's connection to a messenger, e.g. a Telegram bot. |
| Bot | An assistant running in a workspace: its own VM with a persistent home and memory, and its own chat thread. |
| Harness | What a bot runs on: a coding runtime, e.g. the Claude Code CLI or the Codex CLI. |
| Sideworker | A temporary clone of a bot for a separate task in another directory. Same workspace, same permissions. |
| Scout | A one-task VM for access a bot doesn't have or for untrusted sites. Runs only with your approval and reports to you, never to the bot. |
How it works
Install the daemon
house, on your Mac or Linux machine.Create a workspace
Choose which hosts its bots may reach and which secrets they may use.
Connect a messenger
E.g. a Telegram bot.
Add a bot
Pick its harness, e.g. the Claude Code CLI, and set up its VM: a setup script installs the tools and packages it needs.
Talk to it
Write in its thread. It replies there, calling scouts or starting sideworkers when needed.
house onboard walks you through steps 2 to 4 in the terminal.
Network and secrets
All of a bot's traffic goes through the daemon:
- Allowlist. Each workspace lists the hosts its bots may reach; everything else is blocked.
- Placeholders. Bots see only placeholders for API keys and secrets. The daemon substitutes the real value at egress, in the HTTP header of a request to the secret's own hosts, so a leaked placeholder is useless.
- Isolation. Every bot and scout runs in a separate VM. A sideworker sees its parent's home.
- Scouts. No scout runs without your approval: you see the task and its capabilities, and you decide which secrets it gets. It starts in a fresh VM with none of the bot's files, which is deleted when you close it. It sends its result to you in its own thread; the bot gets its text and files only when you pass them on, so hostile content from untrusted sites stays out of the bot's context.
Substitution happens at egress, not inside the VM, so it works only for HTTP(S) clients that send the secret verbatim in a header. Database passwords, SSH keys, request signatures (e.g. AWS SigV4) and anything read from a file need the real value in the VM.
Where it runs
| Part | Supported |
|---|---|
| Machine | macOS on Apple silicon, or Linux with KVM (your own machine, a VM with nested virtualization, or a KVM-enabled VPS) |
| Harnesses | Claude Code CLI, Codex CLI |
| Messengers | Telegram (bot, threaded mode) |