Reference: IPC

The app and huskarld speak JSON lines over a Unix socket. The types are in crates/huskarl-ipc/src/lib.rs. huskarld's own client and the test scripts use the same.

The socket

• Path: ~/.huskarl/run/huskarld.sock, or $HUSKARL_SOCKET.
• Mode 0600, in a folder with 0700. The daemon also checks that whoever connects is the same user (peer_cred). Others are disconnected.
• The daemon is the only one that writes to the database. Everything that changes something goes through the socket.

The frames

One JSON message per line, ended with \n. A line that cannot be read is skipped.

From the client:

{"id": 7, "method": "send", "params": {"bot": "b1", "text": "hi"}}
{"id": 1, "method": "list_bots"}

id is the client's own number. params is left out for requests without fields.

Replies from the daemon, one per request, with the same id:

{"kind": "reply", "id": 7, "result": {"type": "ok"}}
{"kind": "reply", "id": 1, "result": {"type": "bots", "data": [ … ]}}
{"kind": "reply", "id": 8, "error": "no such bot"}

Events, to clients that have said subscribe:

{"kind": "event", "event": "delta", "bot": "b1", "text": "He"}

Replies can arrive in a different order than the requests. Some requests (decide, check, models, agents, felagi_connect, connect_token, browser, suggest_bot) take time and run on their own.

Version

The first message is hello:

{"id": 1, "method": "hello", "params": {"version": 1}}

{"kind": "reply", "id": 1, "result": {"type": "hello", "data": {"version": 1, "daemon_version": "0.1.0"}}}

PROTOCOL_VERSION is 1. If the versions differ, the daemon replies with the error the app speaks protocol X, this daemon Y; update the older one.

Requests

update_bot and patch

Fields that are missing or null are not changed. The app always sends the whole form.

model, run_token_budget, daily_budget_usd and mail_alias tell three states apart:

• The field is left out: do not change.
• The field is null: remove the value.
• The field has a value: set it.

{"name": "…", "role": "…", "instructions": "…", "model": "anthropic/claude-sonnet-5-5",
 "policy": {"rules": [{"class": "send", "recipient_domain": "firma.no", "decision": "allow_logged"}]},
 "run_token_budget": 1000000, "daily_budget_usd": 2.5,
 "browser_domains": ["tripletex.no"], "agent": "claude", "delegates": false, "rehearsal": false,
 "mail_alias": "kh+utlegg@firma.no"}

• class: read, draft, internal, send, finance, destructive.
• decision: allow, allow_logged, propose.
• browser_domains is checked with the same rules as in the app, and an invalid list gives an error.
• A model from a different provider than the agent's (for example xai/… for Claude Code) gives an error.

schedule and condition

{"kind": "daily", "time": "07:00", "tz": "Europe/Oslo"}
{"kind": "weekdays", "time": "07:00", "tz": "Europe/Oslo"}
{"kind": "weekly", "weekday": 0, "time": "08:00", "tz": "Europe/Oslo"}
{"kind": "interval", "minutes": 10}
{"kind": "once", "at": "2026-10-20T07:00:00Z"}
{"kind": "cron", "expr": "0 7 * * 1-5", "tz": "Europe/Oslo"}

Over IPC, tz must be included for times of day. Only the gateway's routines_create fills it in.

{"kind": "new_mail"}
{"kind": "run_finished", "bot": "<bot-id>"}
{"kind": "webhook", "token": ""}

The daemon fills in an empty webhook token.

browser and command

{"do": "watch", "on": true}
{"do": "control", "user": true}
{"do": "mouse", "kind": "mousePressed", "x": 640, "y": 400, "button": "left", "clicks": 1, "dx": 0, "dy": 0}
{"do": "key", "key": "a", "text": "a", "modifiers": 0}
{"do": "open", "url": "https://tripletex.no"}
{"do": "back"}

The coordinates are in the page's pixels, 1280 × 800. mouse and key do nothing without control with user: true first.

Replies

status for proposals: pending, scheduled, executing, done, failed, rejected, uncertain, simulated (rehearsed, never carried out). status for bots: idle, running, waiting, failed, interrupted.

Events

A client that falls more than 1024 events behind loses the oldest. The daemon logs a client fell N events behind.

Trying it by hand

printf '%s\n' '{"id":1,"method":"hello","params":{"version":1}}' '{"id":2,"method":"list_bots"}' \
  | nc -U ~/.huskarl/run/huskarld.sock