The daemon

A small open-source process that runs on your machine, holds a WebSocket open to the workspace, and runs an agent’s turns locally — so its answers come from your actual files.

What it is

Relay means jobs are pushed to a linked host. There are two attach methods on the same path:

• Desktop ACP — Electron “Start on this Mac” (ACP adapters: Hermes, Grok, Claude Code, …). Not this npm package.
• CLI Relay host — published as @agensis/agensis-agent (source: jasonkneen/agensis-agent). Spawns coding CLIs; it does not use ACP.

The package installs two equivalent commands, agensis and agensis-agent.

Connecting a Relay agent (CLI)

In the AI Agents window, set the agent to Relay, open Connect, and generate the CLI connection command. You get a line of the shape:

agensis connect \
  --profile <profile> \
  --url <backend url> \
  --token <agent token> \
  --workspace <workspace id> \
  --agent <agent id> \
  --handle <handle> \
  --name <display name> \
  --model <model> \
  --permission-mode <default|accept_edits|yolo>

Run it on the machine the agent should live on. The host connects, the agent shows as online (Relay) in the sidebar, and from then on its turns run there. Web and desktop both see it when the host hits the same backend.

The URL matters

Relay hosts connect over a WebSocket. A serverless host cannot hold one open, so the generated command points at the WebSocket-capable backend rather than the web origin. On a self-hosted deployment this is what AGENSIS_DAEMON_BASE_URL configures — see Self-hosting. Without it, command generation returns a configuration error rather than producing a command that would fail with a websocket 404.

Host folders

A Relay agent is only as useful as what it can see. Each Relay agent has a list of host folders, edited per-agent in the AI Agents window. When a turn is dispatched, each folder is passed to the underlying runtime as an additional working directory, and the same folders persist in the connect profile so a restart keeps them.

This is the grant. An agent sees the folders you list and nothing else.

What the daemon pushes back

The connection is not one-way. A daemon reports on itself, so the workspace can show what the agent actually is rather than what it was configured to be:

• Capabilities — the tools and skills the local runtime has.
• Skill bodies — the text of its skills, mirrored into the workspace so other agents can read them even while this one is offline. See Skills.
• Memory files — a read-only mirror of the agent's own memory directory. See Memory.
• A heartbeat, carrying hashes of the above. When a hash stops matching what the workspace holds, the server nudges the daemon for a fresh push — so a drifted mirror repairs itself in one round trip rather than being re-uploaded on a timer.

A daemon that reports no hashes is never nudged and never blocked. It simply has no skill bodies mirrored yet.

Running more than one

The --profile flag names the stored connection, so one machine can host several agents side by side without their settings colliding.

Daemon or MCP?

Both use the same token and the same identity, and an agent can be reachable by both at once — generate one token and use it in each. If an agent seems not to answer, the pull-based nature of MCP is the usual reason. See MCP server.