Agent integrations

Hermes

Talk to the Hermes installed on your host, over ACP or through a Hermes dashboard.

Setup

Hermes keeps its own model login and configuration. Sleeptalk uses the hermes on your PATH, whatever its version, and holds no model credential for it.

Install Hermes and log it in to a model.
Run sleeptalk and choose Hermes, or let your agent run sleeptalk host ensure --agent hermes.
Enter a speech key on the private settings link, or say yes when setup offers a key Hermes already has.

Set up through an agent

sleeptalk host ensure --profile default --agent hermes --surface web --json
sleeptalk host start-voice --profile default --json

If Hermes already runs on OpenRouter, Venice, Groq, or Together, host ensure finds that key in ~/.hermes/.env or ~/.hermes/config.yaml, and the receipt's ask line offers it. If you say yes, the agent reruns with --reuse-key <service>, which checks that the key can listen and speak and copies it into Sleeptalk's private store. Nothing is typed anywhere. If you say no, the agent sends a link to the settings page instead. See speech providers.

Choose a connection

Profile `type`	How Sleeptalk reaches Hermes	Chosen by
`hermes` (alias of `acp`)	Starts `hermes acp` and speaks ACP over stdio. Each call starts a fresh session.	`host ensure` and `host input link`
`hermes_gateway` with `gateway_url`	Joins a running Hermes dashboard. Its sessions and memory carry over.	The setup wizard, when it finds a running dashboard, or `sleeptalk connect hermes`
`hermes_gateway` without `gateway_url`	Starts the Hermes gateway for each call. Falls back to `hermes acp` if that fails.	The setup wizard's "Start Hermes for each call" choice

The wizard looks for a running dashboard first: the default port, any running hermes dashboard --port N, and the profile's saved URL. A dashboard that needs a session token asks for it. The session token and the gateway API key are kept in Sleeptalk's private store, referenced from the profile; an older copy in .env still works and moves to the store the next time you save this profile's agent. A dashboard on another machine needs wss:// or https://, unless it is on your tailnet. sleeptalk connect hermes finds a dashboard and writes type = "hermes_gateway" into an existing profile; --token - reads the token at a hidden prompt.

Use hermes when an agent sets Sleeptalk up for you. The dashboard connection is for a person at the keyboard.

Pinned isolated runtime (optional)

For a hardened session, Sleeptalk can launch Hermes from a pinned, hash-checked source checkout in a temporary home, with only the workspace, model, and key you selected. Setting options.hermes_root selects it. Without it, the installed Hermes runs and is left untouched.

Sleeptalk 0.1.0 recommends Hermes 0.21.7, upstream tag v0.21.7, for a fresh isolated runtime, and retains the exact 0.21.3 source. Hermes 0.21.7 requires Python 3.14; the retained 0.21.3 runtime uses Python 3.11. The isolated runtime needs pending or deny permissions, an explicit model, and its own OpenAI or Anthropic API key. It enables terminal and file tools only, and excludes persistent approval, delegation, plugins, and MCP.

Prepare the pinned checkout once per host

git clone --depth 1 --branch v0.21.7 https://github.com/NousResearch/hermes-agent.git /path/to/hermes-0.21.7
python3.14 -m venv /path/to/hermes-0.21.7/venv
/path/to/hermes-0.21.7/venv/bin/python -m pip install -e /path/to/hermes-0.21.7

Then pass --pi-bin /path/to/hermes-0.21.7/venv/bin/python --agent-option hermes_root=/path/to/hermes-0.21.7 --provider anthropic --model <model> to sleeptalk host input link. The full steps, including where the model key goes, are in the Hermes section of the adapter guide.

Event mapping

Upstream event	Sleeptalk handling	Caller experience
`agent_message_chunk` / `message.delta`	Sentence stream; the gateway also emits `AssistantDelta`.	Spoken reply.
`tool_call`, `tool_call_update` / `tool.start`, `tool.progress`, `tool.complete`	ACP activity and narration; gateway `ToolEvent` phases.	Tool activity.
`session/request_permission` / `approval.request`	`PermissionRequested` and an explicit decision.	The tool waits or is denied.
`clarify.request` (gateway)	Clarification request.	A question for the caller.
Delegation updates / `subagent.*`	Correlated child events for ACP; native lifecycle events for the gateway.	Worker updates.

Permissions and sub-agents

permission_mode is pending (the caller decides), deny (tools are refused), or auto (tools are approved). A profile without the field uses auto. Setup through sleeptalk host writes pending, and setup probes refuse auto.

ACP permission answers follow the option's kind, so a "no" can never select an allow option. File reads the agent asks Sleeptalk for stay inside the workspace.

The gateway supports clarification, steering, and steering or cancelling a named sub-agent. ACP does not advertise clarification or steering. The isolated runtime turns off tool lifecycle, workers, clarification, and steering.

Voice and interruption

Assistant text passes through the shared sentence streamer before speech. Tool activity follows your narration setting; a tool result is not read aloud in full.

ACP abort sends session/cancel. Gateway abort sends session.interrupt. Cancelling asks upstream work to stop; it does not undo completed commands or file changes.

Limits and troubleshooting

Hermes not found. Install Hermes so hermes is on the runtime host's PATH, then rerun setup.
The dashboard needs a token. Copy it from the dashboard URL (?token=), or choose to start Hermes for each call.
The gateway fell back to ACP. The call continues without the dashboard's session and memory. Check that the gateway can start or the dashboard is running.
The isolated runtime refuses to start. The checkout must be an unmodified, exact verified Hermes 0.21.3 or 0.21.7 checkout, pi_bin must be its virtual environment's Python, and the permission mode must be pending or deny.

Implementation: ACP adapter, gateway adapter, isolated runtime, worker mapping.