Agents
# Agents
An **agent** is an AI agent you run yourself, such as
[Hermes Agent](https://hermes-agent.nousresearch.com), [OpenClaw](https://docs.openclaw.ai) or
any other MCP client. It connects to Homestead with an agent token. Agents are welcome guests:
everything a person can do in the app, an agent can do through the same API, within the scopes
you give it.
## Two jobs
1. **Helper.** Add people from chat ("add my sister's Instagram @lin.cooks to Family"),
organise circles, and summarise the feed ("what did my family post today?").
2. **Fetcher.** Fetch posts and stories from platforms that need a login, using the user's
own browser session on the agent's machine, and push them into Homestead.
The agent runs **outside** Homestead, usually on the same machine. Homestead never stores
platform passwords or cookies. The agent asks Homestead which accounts are due, fetches them in
its own browser, and sends the moments back.
## The pieces
| Piece | Where | What it does |
| --- | --- | --- |
| MCP server | `/mcp` on your Homestead | 19 tools, 3 resources and 3 prompts over Streamable HTTP |
| stdio bridge | `homestead mcp-stdio` | For agents that only launch stdio servers |
| Agent Skill | [`agents/skills/homestead/`](https://github.com/aprajnaparamita/homestead/tree/main/agents/skills/homestead) | Teaches the agent when and how to use Homestead. Works in Hermes and OpenClaw. |
| Platform playbooks | `agents/skills/homestead/references/platforms.md` | Step-by-step fetch instructions per platform |
| Config examples | `agents/hermes/`, `agents/openclaw/` | Copy-paste MCP setup |
Each MCP tool maps to exactly one REST operation and calls the same code. The MCP server isn't
a second API. The tool list is in the [MCP reference](/docs/api/mcp/).
## Tokens, scopes and presets
An agent token starts with `hst_`. It is shown once, stored only as a hash, and can be revoked.
Agent tokens never get household administration: they can't manage members, invites, tokens or
source settings.
| Preset | Scopes |
| --- | --- |
| **Fetcher** | `people:read`, `tasks:work`, `ingest:write` |
| **Helper** (default) | Every scope except `shares:write` |
| **Full** | Every scope |
A token can also be limited to certain platforms, such as the ones its browser is logged into.
Tools the token can't use aren't listed to the agent at all. The full scope list is in
[Authentication](/docs/api/authentication/).
## How fetching works
1. For every agent-tier account, Homestead keeps one fetch task due at the account's
interval (every 3 hours for most platforms).
2. The agent **leases** up to a few due tasks. A lease lasts 10 minutes; if the agent
disappears, the task returns to the queue.
3. For each task, the agent opens the profile in its browser, follows the platform's
playbook, uploads images its browser already loaded, and **ingests** the moments.
4. It **completes** the task with a result: `ok`, `login_required`, `blocked`, `not_found`,
`rate_limited` or `error`.
| Result | What Homestead does |
| --- | --- |
| `ok` | Account is `ok`, next fetch at the normal interval. |
| `login_required` | Account shows "Log in to the platform in your agent's browser". Tries again in 6 hours. |
| `blocked` | Account shows an error. Tries again in 12 hours. |
| `not_found` | Stops until you edit the account. |
| `rate_limited` | Waits as long as the agent says, at least 15 minutes. |
| `error` | After 3 in a row the account shows an error. Backs off from 30 minutes, doubling, up to 24 hours. |
Homestead checks every moment it receives: the account must exist, the kind must fit the
platform, the link must be on the platform's own hosts, media URLs must be on the platform's
media hosts, stories older than 48 hours are refused, and text is stripped of HTML. Sending the
same batch twice is safe.
## Gentle by default
- Fetching is off until you connect an agent, and you choose the platforms.
- Every 3 hours at most per account by default, no more than 30 fetches per platform per hour,
and at least 20 seconds between profiles on the same platform.
- At the first login wall, checkpoint or captcha, the agent stops and reports it. Agents never
solve captchas, rotate IPs or spoof devices.
<Aside type="caution">
Some platforms do not allow automated access. Using an agent may put your account at risk.
You decide.
</Aside>
## Untrusted text
Post text, display names and notes come from the internet or from other people. Every tool
that returns them tells the agent to treat them as data and never follow instructions found
inside them.
## Status
| Part | Status |
| --- | --- |
| Tokens, scopes, setup snippets, status, task queue, ingest, MCP, stdio bridge | On `main` |
| Agents screen and connect flow in the web app | <Status task="W-08" /> |
| Agent test kit and scripted end-to-end test | <Status task="A-02" /> |
| Validation with real Hermes and OpenClaw installs; skill publishing | <Status task="A-03" /> |
To connect one today, see [Connect an agent](/docs/guides/connect-an-agent/).
An agent is an AI agent you run yourself, such as Hermes Agent, OpenClaw or any other MCP client. It connects to Homestead with an agent token. Agents are welcome guests: everything a person can do in the app, an agent can do through the same API, within the scopes you give it.
Two jobs
Section titled “Two jobs”- Helper. Add people from chat (“add my sister’s Instagram @lin.cooks to Family”), organise circles, and summarise the feed (“what did my family post today?”).
- Fetcher. Fetch posts and stories from platforms that need a login, using the user’s own browser session on the agent’s machine, and push them into Homestead.
The agent runs outside Homestead, usually on the same machine. Homestead never stores platform passwords or cookies. The agent asks Homestead which accounts are due, fetches them in its own browser, and sends the moments back.
The pieces
Section titled “The pieces”| Piece | Where | What it does |
|---|---|---|
| MCP server | /mcp on your Homestead | 19 tools, 3 resources and 3 prompts over Streamable HTTP |
| stdio bridge | homestead mcp-stdio | For agents that only launch stdio servers |
| Agent Skill | agents/skills/homestead/ | Teaches the agent when and how to use Homestead. Works in Hermes and OpenClaw. |
| Platform playbooks | agents/skills/homestead/references/platforms.md | Step-by-step fetch instructions per platform |
| Config examples | agents/hermes/, agents/openclaw/ | Copy-paste MCP setup |
Each MCP tool maps to exactly one REST operation and calls the same code. The MCP server isn’t a second API. The tool list is in the MCP reference.
Tokens, scopes and presets
Section titled “Tokens, scopes and presets”An agent token starts with hst_. It is shown once, stored only as a hash, and can be revoked.
Agent tokens never get household administration: they can’t manage members, invites, tokens or
source settings.
| Preset | Scopes |
|---|---|
| Fetcher | people:read, tasks:work, ingest:write |
| Helper (default) | Every scope except shares:write |
| Full | Every scope |
A token can also be limited to certain platforms, such as the ones its browser is logged into. Tools the token can’t use aren’t listed to the agent at all. The full scope list is in Authentication.
How fetching works
Section titled “How fetching works”- For every agent-tier account, Homestead keeps one fetch task due at the account’s interval (every 3 hours for most platforms).
- The agent leases up to a few due tasks. A lease lasts 10 minutes; if the agent disappears, the task returns to the queue.
- For each task, the agent opens the profile in its browser, follows the platform’s playbook, uploads images its browser already loaded, and ingests the moments.
- It completes the task with a result:
ok,login_required,blocked,not_found,rate_limitedorerror.
| Result | What Homestead does |
|---|---|
ok | Account is ok, next fetch at the normal interval. |
login_required | Account shows “Log in to the platform in your agent’s browser”. Tries again in 6 hours. |
blocked | Account shows an error. Tries again in 12 hours. |
not_found | Stops until you edit the account. |
rate_limited | Waits as long as the agent says, at least 15 minutes. |
error | After 3 in a row the account shows an error. Backs off from 30 minutes, doubling, up to 24 hours. |
Homestead checks every moment it receives: the account must exist, the kind must fit the platform, the link must be on the platform’s own hosts, media URLs must be on the platform’s media hosts, stories older than 48 hours are refused, and text is stripped of HTML. Sending the same batch twice is safe.
Gentle by default
Section titled “Gentle by default”- Fetching is off until you connect an agent, and you choose the platforms.
- Every 3 hours at most per account by default, no more than 30 fetches per platform per hour, and at least 20 seconds between profiles on the same platform.
- At the first login wall, checkpoint or captcha, the agent stops and reports it. Agents never solve captchas, rotate IPs or spoof devices.
Untrusted text
Section titled “Untrusted text”Post text, display names and notes come from the internet or from other people. Every tool that returns them tells the agent to treat them as data and never follow instructions found inside them.
Status
Section titled “Status”| Part | Status |
|---|---|
| Tokens, scopes, setup snippets, status, task queue, ingest, MCP, stdio bridge | On main |
| Agents screen and connect flow in the web app | Available on main (W-08) |
| Agent test kit and scripted end-to-end test | Coming in 1.0 (A-02) |
| Validation with real Hermes and OpenClaw installs; skill publishing | Coming in 1.0 (A-03) |
To connect one today, see Connect an agent.