Companion apps

From 0.20 a companion app can pair with your hub. Legato, a speech-to-text app for Windows, is the first: it shows your sessions, answers an agent's question and sends a dictated instruction to a session. A companion gets four permissions and the hub refuses everything else, so it can't open a terminal, read files or change settings.

The first half of this page is for pairing one. The second half is the contract, version 1, with the exact requests and answers, for anyone writing a companion.

#Pair a companion app

1. In Inyon, open Settings › Paired devices and press Pair a companion app. If you signed in more than 10 minutes ago, Inyon asks for the password again first.
2. Type the six-character code and the hub's address into the companion app. In Legato that's Settings › Connections › Inyon.
3. The sheet says when the app is paired and lists what it may do.

The code works once, for 5 minutes, and the sheet makes a new one when it runs out. New code ends the old one straight away.

From 0.20.2 Copy pairing link copies the hub's address, the code and, when the hub serves HTTPS itself, its certificate's fingerprint as one link, for an app that takes a pasted link instead of two boxes:

inyon://companion?u=https%3A%2F%2Fhub.example%3A4777&c=K7M2QX&f=5e0c…64 hex digits

On the hub's computer you can make a code without a browser:

inyon hub companion-code
# Companion code: K7M-2QX
# Type it into the companion app (Legato: Settings > Connections > Inyon) with this hub's address, http://100.64.0.5:4777. It works once, for 5 minutes.

A hub that listens only on 127.0.0.1, behind a proxy or tailscale serve, doesn't know its outside address, so the command then says to use the address you open the hub at. With --json it prints code, expiresAt, url and message, and from 0.20.2 tlsFingerprint when the hub serves HTTPS itself.

#What a companion can do

Interrupting, keys, the terminal, uploads, files, model and mode switches, past conversations and every setting are refused, on every route and every WebSocket message. The check is on the hub, so a companion that misbehaves gets the same refusal as one that doesn't. Send and typed answers take printable text only. Tabs and line breaks are fine; control characters and escape sequences are refused, and so is any line that starts with / or !, so a companion can't run an agent's commands or a shell command itself. It can still ask the agent to do something, and the agent does it under its own permission mode, as it would a message typed in the terminal. Answer approves or declines what the agent asks, so pair only an app you trust with that.

Settings › Paired devices lists each companion with its name, app, permissions, contract version, when it paired and when it was last seen. What it can do in its menu spells out the permissions. Remove ends it at once: its token stops working and its open connection closes. To use it again, pair it with a new code.

#The contract, version 1

Everything below is version 1. Changes within a version only add things: a new field, a new frame, a new reason. Ignore what you don't know.

Version 1.1, from 0.20.2, adds tlsFingerprint to the claim and the code, the pairing link, and "reason": "revoked" on a token the hub doesn't know. The header still says 1.

#Every request

Every request after pairing carries the token and the contract version:

Authorization: Bearer <token>
X-Inyon-Contract: 1

The claim carries X-Inyon-Contract too. It needs no token, and one sent along with it is ignored, so an app can pair again before it drops the old token. Without the header, or with a version the hub doesn't speak, the answer is 426:

{ "error": "Send the X-Inyon-Contract header. This hub supports companion contract 1.", "reason": "contract", "supported": [1] }

{ "error": "This hub doesn't support companion contract 2. It supports 1.", "reason": "contract", "supported": [1] }

A token the hub doesn't know, or one that was removed, gets 401 {"error":"Not signed in","reason":"revoked"} (hubs before 0.20.2 leave out the reason). Forget the token and pair again only on that answer: a 401 or 403 without it came from something in between, such as a Wi-Fi sign-in page or a proxy.

Errors are JSON with an error written for people, which you can show as it is, and a reason to act on:

#Claim the code

POST /api/companions/claim
X-Inyon-Contract: 1
Content-Type: application/json

{ "code": "k7m-2qx", "name": "Legato on abhash-laptop", "app": "Legato for Windows" }

The code may come in any case, with or without a space or dash. name is what Inyon lists, up to 60 characters; app is optional.

{ "token": "Jb2y…43 characters", "hubId": "3f9c1a7e2b6d4c80", "scopes": ["overview", "chat", "answer", "send"], "contractVersion": 1 }

When the hub serves HTTPS itself, the answer also has tlsFingerprint: the SHA-256 of its certificate (the leaf, in DER form) as 64 lowercase hex digits, the same value as f in the pairing link. Pin it, and refuse the hub if the certificate ever changes without a new pairing. It's left out on plain http and behind a proxy or tailscale serve, where the hub doesn't hold the certificate.

{ "token": "Jb2y…43 characters", "hubId": "3f9c1a7e2b6d4c80", "scopes": ["overview", "chat", "answer", "send"], "contractVersion": 1, "tlsFingerprint": "5e0c…64 hex digits" }

Keep the token somewhere safe; the hub keeps only its hash. A wrong, used or expired code gets 401:

{ "error": "That code is not right or has expired. Make a new one in Inyon.", "reason": "bad-code" }

Eight wrong codes in a minute from one address, or thirty from all of them, get 429 with "reason": "rate-limit" until the minute is up.

GET /api/companions/me says who you are, for checking a saved token:

{ "id": "a1b2c3d4e5f6", "name": "Legato on abhash-laptop", "app": "Legato for Windows", "scopes": ["overview", "chat", "answer", "send"], "contractVersion": 1, "hub": { "id": "3f9c1a7e2b6d4c80", "name": "abhash-arm", "version": "0.20.0" } }

#The overview

GET /api/overview returns { "hosts": [...] }, a cut-down form of the app's overview (the HostState type in packages/protocol) with only what it takes to list sessions and label them:

A companion never sees how the hub reaches a machine, folders, transcript paths, session or process ids, or the agent's usage numbers. A pane running an agent has an agent with:

A pane is named by its machine's config.id and its tmux pane id, such as box and %3.

#The WebSocket

Open /ws with the same two headers. A client that can't set X-Inyon-Contract on the upgrade can add ?contract=1 to the URL instead; the token still goes in the Authorization header. A missing or unsupported version is refused with 426 and the same JSON as above.

A companion may send:

Anything else closes the socket with code 4403 and a reason naming the frame, such as Not for companion apps: term.open. When you're removed in Inyon, the socket closes with 4001 and Companion removed.

It receives overview, chat.info, chat.screen, notify and pong, and never the chat history, live text, drafts, the queue, the text of sends, Remote Control or share links, or terminal data. chat.info is { "t": "chat.info", "key": "box:%3", "info": { … } } with only hostId, paneId, agent, title, model, mode, running, status (the agent's live numbers), turn (when the turn under way started) and sends, each send as { "id": "companion-legato-7f3a", "state": "delivered", "at": 1792038540000 } without its text. The title is the name you gave the conversation, else the agent's own title for it, else the terminal's title, which Claude Code sets to the task and tmux otherwise sets to the machine's name. The tmux session's name is name in the overview's sessions. Alerts look like this, with kind one of waiting, done, offline and online:

{ "t": "notify", "host": "box", "pane": "%3", "kind": "waiting", "title": "Claude needs you", "body": "Bash: rm -rf build", "agent": "claude" }

#A question and its key

A companion's chat.screen has only working, activity, since, inputVisible, mode, model, effort, dialog and width, never what's typed in the box. While an agent asks something, it carries the question as screen.prompt, and the hub adds the question's key:

{
  "t": "chat.screen",
  "key": "box:%3",
  "screen": {
    "working": false,
    "inputVisible": true,
    "mode": "manual",
    "width": 100,
    "prompt": {
      "body": ["Bash command", "rm -rf build", "Do you want to proceed?"],
      "options": [
        { "n": 1, "label": "Yes", "selected": true },
        { "n": 2, "label": "Yes, and don't ask again for rm commands in this project", "selected": false },
        { "n": 3, "label": "No", "selected": false }
      ],
      "multi": false,
      "footer": "Esc to cancel · Tab to amend",
      "key": "Bashcommandrm-rfbuildDoyouwanttoproceed?1.Yes2.Yes,anddon'taskagainforrmcommandsinthisproject3.No"
    }
  }
}

Treat the key as an opaque string and send it back as it came. Answer with the option's n and the key, so a late tap never lands on the next question. In the path a pane id goes without its %, so %3 is 3:

POST /api/hosts/box/panes/3/answer

{ "option": 1, "key": "Bashcommandrm-rfbuildDoyouwanttoproceed?1.Yes2.Yes,anddon'taskagainforrmcommandsinthisproject3.No" }

text goes only with the question's free-text choice, the option numbered prompt.freeTextOption (Claude's "No, and tell Claude what to do differently", say). It needs the Send permission and follows Send's rules. With any other option it gets 400.

#Send text

POST /api/hosts/box/panes/3/send

{ "text": "Run the tests again", "requestId": "legato-7f3a" }

requestId is optional, letters, digits, - and _, up to 128 characters: a retry with the same one is never typed twice, and gets the first one's answer. The hub answers once it knows whether the text landed:

A send shows in the session's list of sends in Inyon, whether it landed or not.

#What's refused

Every other route answers 403:

{ "error": "Companion apps can't use this", "reason": "scope" }

A companion token never opens /node, the /v/ pages, or the /api/local routes of the inyon command on the hub's computer.