Connect an agent

This guide connects an AI agent to Homestead so it can add people from chat and fetch posts from platforms that need a login. Read Agents first if you haven’t.

Caution

Some platforms do not allow automated access. Using an agent may put your account at risk. You decide.

Before you start

• A running Homestead your agent can reach. If the agent runs on another machine, see Remote access and set HOMESTEAD_BASE_URL.
• Hermes, OpenClaw or another MCP client.
• For fetching: a browser profile on the agent’s machine that’s already logged in to the platforms you want, such as Instagram or Douyin. Homestead never asks for those passwords.

1. Create a token

Agents screen

Available on main (W-08)

In the web app, go to Agents → Connect an agent. Pick Hermes, OpenClaw or Other, a preset (Helper is the default) and, optionally, the platforms the agent’s browser is logged in to. Homestead creates the token and shows a setup card with the token already filled into each snippet. The card turns green when the agent first uses the token.

Command line

The homestead token create command does the same from the server’s shell. With Docker:

docker exec homestead homestead token create --name "Hermes on homeserver" --agent-kind hermes --preset fetcher --platforms instagram,douyin

Flag	Meaning
--name	Required. Shown in the app.
--preset	fetcher, helper or full. Default helper.
--scopes	Comma-separated scopes, such as people:write,ingest:write. Overrides --preset.
--agent-kind	hermes, openclaw or other. Default other.
--platforms	Comma-separated platform IDs. Empty means every agent-tier platform.

The command prints the token on its own line. Copy it now: it’s shown once and can’t be recovered. The full flag reference is in the CLI reference.

2. Install the skill

The Homestead skill teaches the agent when to use Homestead, how to add people and how to run a fetch round, with per-platform playbooks.

• Hermes: copy the agents/skills/homestead/ folder into ~/.hermes/skills/homestead/.
• OpenClaw: copy the folder into your workspace’s skills/ directory.

Publishing the skill to the Hermes Skills Hub and ClawHub hasn’t happened yet. Coming in 1.0 (A-03)

3. Add the MCP server

Your MCP URL is your Homestead address plus /mcp, for example http://homestead.local:8080/mcp. The token goes in an Authorization header.

Hermes

Merge this into ~/.hermes/config.yaml (from agents/hermes/config.example.yaml):

mcp_servers:
  homestead:
    url: "http://homestead.local:8080/mcp"
    headers:
      Authorization: "Bearer hst_REPLACE_WITH_YOUR_TOKEN"
    timeout: 120
    connect_timeout: 30

OpenClaw

Merge this into ~/.openclaw/openclaw.json (from agents/openclaw/openclaw.example.json5):

{
  mcp: {
    servers: {
      homestead: {
        url: "http://homestead.local:8080/mcp",
        transport: "streamable-http",
        headers: { Authorization: "Bearer hst_REPLACE_WITH_YOUR_TOKEN" },
        enabled: true,
        requestTimeoutMs: 120000,
      },
    },
  },
}

Then check the connection:

openclaw mcp doctor homestead --probe

OpenClaw recommends keeping secret headers out of config literals with its own secrets mechanism; see its documentation.

Other MCP clients

Use the Streamable HTTP URL with this header:

Authorization: Bearer hst_REPLACE_WITH_YOUR_TOKEN

If your client can only launch stdio servers, use the bridge built into the homestead binary. It accepts the server origin or the full /mcp URL:

homestead mcp-stdio --url https://homestead.example.ts.net --token hst_REPLACE_WITH_YOUR_TOKEN

Without the binary on the agent’s machine, the locally built image can run the bridge:

docker run -i --rm homestead mcp-stdio --url https://homestead.example.ts.net --token hst_REPLACE_WITH_YOUR_TOKEN

Agents without MCP can use the REST API directly with the same token, using the HOMESTEAD_URL and HOMESTEAD_TOKEN environment variables the skill reads. See API examples.

4. Test it

Ask your agent:

Homestead, who’s in my Family circle?

It should answer with names from your Homestead. If the Agents screen is open, the card turns green.

5. Schedule fetching (optional)

Fetching needs the tasks:work and ingest:write scopes, which all three presets include. Add a job to your agent’s scheduler that runs the Homestead skill’s fetch round every 3 hours. The MCP server also offers a fetch_round prompt for this.

Each round leases due tasks for the platforms the browser is logged in to, fetches at most one profile every 20 seconds per platform, and stops after 15 minutes or when nothing is due.

Check that it worked

• The token’s last-used time updates (GET /api/v1/agent/status, or the Agents screen).
• After a fetch round, posts from Instagram or Douyin people appear in the feed.
• If an account shows login_required, log in to that platform in the agent’s browser. The next try is 6 hours later.

Revoke a token

Revoke from the Agents screen Available on main (W-08), or with DELETE /api/v1/agent/tokens/{tokenId} as a member. Tasks the agent had leased go back to the queue.