Custom agents

Put your own agent behind the ironwire app. One JSON file on the machine describes it; the agent speaks either ACP over stdio or the relay contract over loopback HTTP. This page is the full reference for both.

Everything here happens on an agent machine: one created from the wireling image (create <name> --image=wireling, or any machine created from the app except a Plain Ubuntu one). A machine on the default image has no daemon, no /etc/wireling and nothing for the app to talk to. For what the app itself does, see the app & agents.

What ironwire gives an agent

Everything a machine offers someone building an agent on it, one line each, with where it is documented. Use these rather than bringing your own: there is no need for a tunnel, a notification service, a scheduler or a chat UI of your own.

Two shapes: ACP or relay

The machine runs a small daemon that sits between the app and the agent. It can drive an agent in two ways, and the question that picks one is who owns the conversation.

Choose ACP for a coding agent or any engine that answers a prompt and holds nothing the machine cannot restart: you get the model picker and process handling for free, and the same binary works in every other ACP client (Zed, JetBrains). Choose relay for an assistant that lives whether or not the app is open: one with its own memory, scheduled jobs or other messaging surfaces, or a thin service you would rather write as an HTTP handler than as an ACP server. Relay is the smaller contract; ACP is the richer integration.

In the app the two are indistinguishable: same picker, same chats, same notifications. The label comes from the manifest and nothing marks which shape is behind it.

The manifest

One JSON file per agent in /etc/wireling/agents.d/. The filename is yours; it must end in .json. The machine ships one such file already, for pi, which is the smallest complete example:

root@scout:~# cat /etc/wireling/agents.d/pi.json
{
  "kind": "pi",
  "label": "Pi",
  "bin": "/usr/local/bin/pi-acp"
}

When it is read

The folder is watched. A new file joins the app's agent picker within a second or two, with no restart of anything. A file that is already loaded is not re-read: editing or removing it takes effect at the next agent restart (chat settings → Agent session → Restart agent). Files load in filename order, and two files naming the same kind keep the first.

Fields common to both shapes

ACP fields

{
  "kind": "myagent",
  "label": "My agent",
  "bin": "/usr/local/bin/myagent-acp",
  "args": ["--acp"],
  "models": [{"id": "fast"}, {"id": "deep", "label": "Deep"}],
  "modelEnv": "MYAGENT_MODEL"
}

Relay fields

{
  "kind": "butler",
  "label": "Butler",
  "relay": "http://127.0.0.1:8700/inbound",
  "commands": [
    {"name": "status", "description": "What the butler is working on"},
    {"name": "remind", "description": "Set a reminder", "argHint": "<when> <what>"}
  ]
}

Strictness

The file is strict, so that a typo never silently does nothing. Each of these rejects the file: an unknown field at any level; a relative bin; both or neither of bin and relay; a reserved or malformed kind; modelEnv without models; an empty models array; args, models or modelEnv together with relay; contract, commands, auth or setup together with bin; a contract that is not an integer, or names a version the machine does not speak (relay contract 2 is not supported by this machine (supports: 1)).

A rejected file is skipped, not fatal: the built-ins and every valid file still load. The reason is in the machine's log, and that log is the first place to look when an agent does not appear:

root@scout:~# journalctl -u wireling-daemon | grep 'agent manifest'
agent manifest /etc/wireling/agents.d/butler.json skipped: "relay" must be a loopback http URL

What every custom agent gets

Whichever shape you pick, the machine handles the chat around your agent:

Signing in is yours. A custom agent is assumed to be set up: the app shows it as Ready and has no Connect button for it. Give it keys as environment variables or run its own login over SSH (inside tmux if it is interactive). An agent that is not configured simply fails its turn. The one exception is a relay that declares auth and setup.

Reaching the owner: wireling

Anything on the machine, your agent included, reaches the owner's chats with the wireling command, or by writing the same requests to the reach socket /run/wireling-reach.sock directly (one JSON object per line, as in replying). Both reach this machine's chats and nothing else.

from says who is speaking. With --from researcher the app shows a note as from researcher and a turn as started by researcher, and a schedule carries the name onto every turn it starts. It is a display name, 1–32 characters on one line, and grants nothing: it never changes which chat is used or what may be done. Without it, notes and turns are labelled as before (from a script, started by your schedule).

Which chat. Inside a turn, wireling uses the chat the turn belongs to (IRONWIRE_CHAT_ID). Anywhere else, a cron job or a service, pass --chat; without one, a note or a run goes to the machine's default chat, and a schedule gets a new chat of its own. An unknown id is refused: no such chat: <id>.

Limits. note, run and chat.new share one rate limit, 30 per five minutes per machine with a burst of 10; over it the reply is {"error": "rate limited"}. chats is not limited.

ACP agents

The machine is an ACP client, in the role an editor normally plays, and your program is the ACP agent. Nothing ironwire-specific is required of it. If your agent does not speak ACP, put an adapter in front of it, as pi does with pi-acp. The protocol itself is documented at agentclientprotocol.com; what follows is how this particular client behaves.

How the program is run

Expect to be restarted. The machine keeps one agent process alive at a time: the one for the chat that ran last. It is started by a chat's turn and reused for that chat's following turns. It is killed, with SIGKILL and no warning, when a different chat takes a turn, when the chat's model changes, after a turn is stopped or fails, and on an agent restart. Keep nothing in memory that you cannot rebuild, and implement session loading (below) if the agent should remember a chat.

The conversation

Session loading. If the chat has a session id but you did not advertise loadSession, or the load fails, the machine opens a new session and tells the owner once per chat: this agent could not restore its memory of this chat, so it is continuing fresh. Because the process is restarted often, an agent without loadSession forgets a chat whenever the owner visits another one.

The ironwire tools. The ironwire MCP server gives the agent the owner's connections and the fleet commands, authenticated as this machine. If your agent refuses a session that carries MCP servers, the machine retries once with none and the chat runs without those tools; the log names the agent and its reason.

How a turn ends. A stopReason of refusal ends the turn as a failure. Any other stop reason ends it normally. The process exiting, or the connection breaking, before the prompt resolves is a failure.

Updates the app shows

Permission requests (session/request_permission) are never shown to the owner. The machine is the sandbox, so the client answers at once, choosing an allow_always option if there is one, otherwise allow_once, otherwise the first option offered. During a stop it answers cancelled.

Models

Two ways to offer a model choice, and they combine:

A model change in chat settings applies from the chat's next turn: the process is started again with the new choice. A chat on Default gets neither the variable nor the config call.

Images

If you advertise promptCapabilities.image, each image arrives as a prompt block {"type": "image", "mimeType", "data"} with base64 data, ahead of the text block. If you do not, images are dropped and only the text is sent; the log records how many were ignored.

A complete ACP agent

This is a whole agent in Python with no dependencies. It answers every message with an echo. For a real agent use an ACP SDK, which also handles cancellation while a prompt is running.

#!/usr/bin/env python3
import json, sys, uuid

def send(msg):
    sys.stdout.write(json.dumps({"jsonrpc": "2.0", **msg}) + "\n")
    sys.stdout.flush()

for line in sys.stdin:
    msg = json.loads(line)
    method, rid, params = msg.get("method"), msg.get("id"), msg.get("params", {})
    if method == "initialize":
        send({"id": rid, "result": {"protocolVersion": 1, "agentCapabilities": {}}})
    elif method == "session/new":
        send({"id": rid, "result": {"sessionId": uuid.uuid4().hex}})
    elif method == "session/prompt":
        text = "".join(b["text"] for b in params["prompt"] if b["type"] == "text")
        send({"method": "session/update", "params": {
            "sessionId": params["sessionId"],
            "update": {"sessionUpdate": "agent_message_chunk",
                       "content": {"type": "text", "text": "You said: " + text}},
        }})
        send({"id": rid, "result": {"stopReason": "end_turn"}})
    elif rid is not None:
        send({"id": rid, "error": {"code": -32601, "message": "method not found"}})

root@scout:~# install -m 755 echo-acp.py /usr/local/bin/echo-acp
root@scout:~# cat > /etc/wireling/agents.d/echo.json <<'EOF'
{ "kind": "echo", "label": "Echo", "bin": "/usr/local/bin/echo-acp" }
EOF

Relay agents

A relay agent is a service on the machine. The machine hands each message to it with an HTTP POST, and the service sends the reply back by writing to the machine's reach socket. There is no process for the machine to manage and no library to adopt: the whole contract is below. This is relay contract v1.

app ──▶ machine daemon ──POST {message}──▶ your service   (loopback http)
app ◀── machine daemon ◀──turn.delta / turn.tool / turn.done──   (reach socket)

Compatibility

The machine's daemon is updated by the platform, on every machine, without you doing anything; your service is not. So the contract changes only in ways that cannot break a service written against it:

1. Within a version, changes are additive only. New fields, new message types and new reach-socket operations may appear. Nothing is removed, renamed or changed in meaning.
2. Ignore what you do not recognise: an unknown field in a message, or a message type you do not handle. Answer an unknown type with a 2xx and do nothing.
3. A breaking change is a new version. A machine keeps speaking each older version to every manifest that declares it ("contract"), so a service keeps working until its author moves it.

The reach socket has no version of its own and follows the same rule. To find out whether a machine has an operation, try it: one it does not know answers unknown op: ….

The message you receive

One POST to the manifest's relay address per turn, Content-Type: application/json:

{
  "v": 1,
  "type": "message",
  "chat_id": "3f2b8c1e-7a40-4d8e-9b1c-5e6f7a8b9c0d",
  "turn_id": "t_9d41c0e2a7b34f6e8c1d2a3b4c5d6e7f",
  "text": "summarise the report\n\nAttached: report.pdf",
  "images": [{"mime": "image/png", "data_b64": "iVBORw0KGgo…"}],
  "cwd": "/root/workspace",
  "origin": "user"
}

Accepting it

Answer the POST straight away and do the work afterwards. Any 2xx status accepts the turn; the reply itself travels over the reach socket, not in the response. The response body may be empty, or a JSON object with an optional session string, which is recorded with the chat as its session id. It is not sent back to you.

Replying: the reach socket

The reach socket is a unix socket at /run/wireling-reach.sock. Connect, write one JSON object on one line, read one JSON object on one line. A connection may carry any number of requests, one after another. There is no credential: being inside the machine is the permission. Every request has an op; every reply is {"ok": true} or {"error": "…"}.

→ {"op": "turn.delta", "turn_id": "t_9d41…", "text": "Reading the report. "}
← {"ok": true}
→ {"op": "turn.tool", "turn_id": "t_9d41…", "id": "1", "kind": "read", "title": "report.pdf", "input": {"file_path": "report.pdf"}}
← {"ok": true}
→ {"op": "turn.tool", "turn_id": "t_9d41…", "id": "1", "title": "report.pdf", "output": "42 pages"}
← {"ok": true}
→ {"op": "turn.delta", "turn_id": "t_9d41…", "text": "It argues three things…"}
← {"ok": true}
→ {"op": "turn.done", "turn_id": "t_9d41…"}
← {"ok": true}

The turn.* requests are not rate limited, so stream as finely as you like.

How a turn ends

Silence is measured from your last activity, not from the start of the turn, and the clock starts when the POST is accepted. A task may run for hours as long as something arrives at least every five minutes; a progress line or a tool card is enough.

Nothing late gets through. Once a turn has ended, for any reason, every further turn.* request for it is refused with no such turn. A slow reply can never leak into the next turn. If your agent has something to say after the turn is over, send it as a note.

Stop

When the owner presses Stop, the turn ends on the machine's side immediately and you are told with a second POST to the same address:

{"v": 1, "type": "stop", "chat_id": "3f2b8c1e-7a40-4d8e-9b1c-5e6f7a8b9c0d", "turn_id": "t_9d41c0e2a7b34f6e8c1d2a3b4c5d6e7f"}

It is sent once, best effort, and nothing waits for your answer. Treat it as a request to abandon that work. Whatever you still send for that turn is refused.

Speaking first: notes

A message your agent starts by itself (a scheduled job's result, a reminder, a question) is a note: it appears in the chat with no turn. Send it on the same socket:

→ {"op": "note", "text": "Your 8am summary is ready.", "source": "agent", "chat": "3f2b8c1e-7a40-4d8e-9b1c-5e6f7a8b9c0d"}
← {"ok": true, "chat_id": "3f2b8c1e-7a40-4d8e-9b1c-5e6f7a8b9c0d"}

Notes are rate limited, unlike the reply stream: 30 per five minutes for the whole machine, with a burst of 10. Over the limit the reply is {"error": "rate limited"}. A note may also be sent while a turn is open. The shell equivalent is wireling note --chat <id> [--from <name>] <text>.

Sign-in from the app (optional)

By default a relay agent is shown as Ready and signs in over SSH like any custom agent. A manifest may instead describe how to tell whether it is signed in, and how to sign it in, and the app then offers Set up with a sheet of providers and a terminal, as it does for the built-in agents.

auth is one of two probes, never both:

setup has two fields, both required:

{
  "kind": "butler",
  "label": "Butler",
  "relay": "http://127.0.0.1:8700/inbound",
  "auth": { "file": "/root/.butler/auth.json", "contains": "access_token" },
  "setup": {
    "login": ["/usr/local/bin/butler", "login", "--provider", "{provider}"],
    "providers": [
      { "id": "openai", "label": "OpenAI", "note": "Uses your ChatGPT plan's included usage." },
      { "id": "api-key", "label": "API key", "note": "Billed per token to the key you paste." }
    ]
  }
}

Declare the two together. With auth alone, an agent that is signed out is simply not usable from the app until someone signs it in over SSH.

Running the service

Your service must listen on a loopback address, be up whenever the machine is, and come back by itself after a restart. A systemd unit does all of that:

root@scout:~# cat > /etc/systemd/system/butler.service <<'EOF'
[Unit]
Description=Butler agent
After=network.target

[Service]
ExecStart=/usr/local/bin/butler serve
Restart=always
EnvironmentFile=/run/ironwire/env

[Install]
WantedBy=multi-user.target
EOF
root@scout:~# systemctl enable --now butler

A systemd service does not see the variables a login shell gets. The EnvironmentFile line gives the service your account and machine environment variables and the IRONWIRE_* identity, which the ironwire command needs.

Two things to keep in mind. Your state is keyed on chat_id and must survive your own restarts, since the machine keeps the chat and will keep sending messages for it. And a restart of the machine's agent software (or of the machine) ends any open turn: requests for it start answering no such turn, and the owner's next message opens a new one.

A complete relay agent

A whole relay agent in Python with no dependencies. It answers the POST at once and replies from a thread.

#!/usr/bin/env python3
import json, os, socket, threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

REACH = os.environ.get("WIRELING_REACH_SOCK", "/run/wireling-reach.sock")

def reach(op, **fields):
    """One request line out, one reply line back."""
    with socket.socket(socket.AF_UNIX) as s:
        s.connect(REACH)
        s.sendall((json.dumps({"op": op, **fields}) + "\n").encode())
        return json.loads(s.makefile().readline())

def answer(msg):
    turn = msg["turn_id"]
    reach("turn.delta", turn_id=turn, text="You said: ")
    reach("turn.delta", turn_id=turn, text=msg["text"])
    reach("turn.done", turn_id=turn)

class Inbound(BaseHTTPRequestHandler):
    def do_POST(self):
        msg = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
        self.send_response(200)
        self.send_header("Content-Length", "0")
        self.end_headers()
        if msg["type"] == "message":
            threading.Thread(target=answer, args=(msg,), daemon=True).start()

    def log_message(self, *args):
        pass

ThreadingHTTPServer(("127.0.0.1", 8700), Inbound).serve_forever()

root@scout:~# python3 echo-relay.py &
root@scout:~# cat > /etc/wireling/agents.d/echo-relay.json <<'EOF'
{ "kind": "echo-relay", "label": "Echo (relay)", "relay": "http://127.0.0.1:8700/inbound" }
EOF

Tool cards

Both shapes feed the same cards. A card is chosen by the call's kind (ACP's kind on a tool call, or the kind field of turn.tool) and filled from its input (ACP's rawInput, or input). The kinds are ACP's standard tool categories.

A card's subtitle comes from description, file_path, pattern or url in the input. When none of those is present, the title is used as the description, so a card with only a title still reads well. Each call id produces one card: send the input with, or before, the result.

Debugging