Server protocol

Protocol version 16 is JSON-RPC 2.0 over one WebSocket, with one message per text frame. The client sends ipc.hello first, then requests. The server answers them and pushes ipc.signal notifications.

The tables come from src/ipc/protocol.ts and src/chat/host/signals.ts. The JSON examples come from a real server run with a scripted provider. The local daemon speaks the same protocol over a unix socket. zidane/ipc and zidane/ipc/remote type it for TypeScript clients.

Connect#

The token travels in a header or a subprotocol:

A proxy can log Sec-WebSocket-Protocol. Use the header where the runtime can set it.

const ws = new WebSocket('wss://zidane.example.com', ['zidane', `zidane.bearer.${token}`])

HTTP on the same port#

The port also answers plain HTTP. GET /healthz needs no token. A refused upgrade gets its status before any JSON-RPC. Captured answers:

[
  {
    "title": "health",
    "request": {
      "method": "GET",
      "path": "/healthz",
      "headers": []
    },
    "status": 200,
    "body": "ok"
  },
  {
    "title": "no token",
    "request": {
      "method": "GET",
      "path": "/",
      "headers": [
        "Upgrade",
        "Connection",
        "Sec-WebSocket-Key",
        "Sec-WebSocket-Version"
      ]
    },
    "status": 401,
    "body": "Unauthorized"
  },
  {
    "title": "unknown token",
    "request": {
      "method": "GET",
      "path": "/",
      "headers": [
        "Upgrade",
        "Connection",
        "Sec-WebSocket-Key",
        "Sec-WebSocket-Version",
        "Sec-WebSocket-Protocol"
      ]
    },
    "status": 401,
    "body": "Unauthorized"
  },
  {
    "title": "browser origin",
    "request": {
      "method": "GET",
      "path": "/",
      "headers": [
        "Upgrade",
        "Connection",
        "Sec-WebSocket-Key",
        "Sec-WebSocket-Version",
        "Origin",
        "Sec-WebSocket-Protocol"
      ]
    },
    "status": 403,
    "refusal": "origin",
    "body": "Forbidden: origin not allowed"
  }
]

Every refusal.

POST /zidane/pair trades a pairing code for a token (pairing). GET /zidane/media serves a workspace's images, videos and audio to a page that plays them by address, under the ticket its connection registered (files.mediaTicket, below). GET /zidane/oauth/callback takes a browser client's MCP sign-in back (auth.oauth.begin, below). With the web app on, every other plain GET serves the app; upgrades on any path still reach the WebSocket, so the app connects to wss://<host>/.

Handshake#

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "ipc.hello",
  "params": {
    "protocolVersion": 13,
    "appVersion": "docs",
    "pid": 4242
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "protocolVersion": 13,
    "appVersion": "docs",
    "pid": 28973,
    "startedAt": 1791968973803,
    "buildId": "1791968503753",
    "codeVersion": "8.0.4",
    "hostId": "08b260f9-090c-445b-957a-1b6f4822f245",
    "hostKind": "server",
    "hostName": "docs-box",
    "signalEpoch": "ed173759-2d4f-436a-b39a-36c1c969e088",
    "remoteInstalls": true,
    "sync": true
  }
}

ipc.hello params#

ipc.hello result#

remoteInstalls, sync, machineServe and projectTerminals say what this server offers. An absent field means no. clone and createFolders say whether clients may clone into the workspace roots and create folders there (allowClone, allowCreateFolders); an older server leaves them out. methods lists what this connection may call: the server's methods within the token's scope (Scopes). A client shows what it lists instead of failing on the rest. hostId stays the same across restarts. A client that saved the server checks it on every connect and refuses another server at the same URL. signalEpoch names this server process for resume. adminCommands ({ token, pair }) are the commands that mint an admin token or an admin pairing code, run on the server's machine with its binary, its user and its data dir. The apps show them to a chat token.

Compatibility#

Each side speaks a range of versions, from its minProtocolVersion to its protocolVersion. A server accepts a client whose range overlaps its own, and the connection speaks the higher version both share (negotiatedProtocolVersion in the result). A client that sends no minProtocolVersion speaks its protocolVersion only. A release keeps the previous version in its range when it raises the current one, so apps built against one release keep working against the next. Ranges that don't overlap get VersionMismatch, with the server's hello fields in data.daemon and the side to upgrade in the message:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32010,
    "message": "Protocol version mismatch: the server speaks v13, the client v12. Upgrade the client.",
    "data": {
      "daemon": {
        "protocolVersion": 13,
        "appVersion": "docs",
        "pid": 28973,
        "startedAt": 1791968973803,
        "buildId": "1791968503753",
        "codeVersion": "8.0.4",
        "hostId": "08b260f9-090c-445b-957a-1b6f4822f245",
        "hostKind": "server",
        "hostName": "docs-box"
      }
    }
  }
}

Within a shared version, the server ignores buildId and codeVersion, so older and newer clients attach. Only breaking changes to the method map or the signal union bump the version.

New methods and fields arrive without a bump. A client treats MethodNotFound (-32601) as "not offered". daemon.shutdown does nothing on a server. No client can drain or restart one.

Before the handshake, the server answers only ipc.hello, $/ping, daemon.info and daemon.shutdown:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32011,
    "message": "Handshake required: send ipc.hello first."
  }
}

Requests and notifications#

Every method takes an object as params and answers with a result or an error. A call without an id runs as a notification. The server sends no answer and drops errors. Drafts use notifications for every keystroke.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "sessions.create",
  "params": {
    "cwd": ""
  }
}

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "id": "7f6b2bc1-27b2-4052-a2b7-de05d2538178",
    "title": "New session",
    "projectRoot": "/data/workspaces",
    "cwd": "/data/workspaces",
    "agentId": "build",
    "status": "idle",
    "createdAt": 1791968973862,
    "updatedAt": 1791968973862,
    "archived": false,
    "hostId": "08b260f9-090c-445b-957a-1b6f4822f245"
  }
}

cwd: '' asks for the server's first workspace root. A folder outside the workspace roots is refused.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "chat.send",
  "params": {
    "sessionId": "7f6b2bc1-27b2-4052-a2b7-de05d2538178",
    "prompt": "Say hello."
  }
}

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "runId": "6f577015-ffbf-4204-ba81-320f71e76f46"
  }
}

chat.send answers once the run starts. The run itself arrives as signals.

Signals#

The server pushes host events as ipc.signal notifications whose params are the signal, kind first. A session signal also carries $seq, its number in that session (from 1, without gaps, within one server process). Signals without a session, such as presence:changed, have none.

The run above, in order: run:start, plans:snapshot, prompt-turns, one event per streamed piece, stream:progress, turn:end, run:end.

{
  "jsonrpc": "2.0",
  "method": "ipc.signal",
  "params": {
    "kind": "run:start",
    "sessionId": "7f6b2bc1-27b2-4052-a2b7-de05d2538178",
    "runId": "6f577015-ffbf-4204-ba81-320f71e76f46",
    "$seq": 4
  }
}

{
  "jsonrpc": "2.0",
  "method": "ipc.signal",
  "params": {
    "kind": "event",
    "sessionId": "7f6b2bc1-27b2-4052-a2b7-de05d2538178",
    "event": {
      "kind": "markdown",
      "text": "H",
      "streaming": true,
      "turnId": "999068c5-c52b-4ccd-a936-682bea162657"
    },
    "$seq": 7
  }
}

{
  "jsonrpc": "2.0",
  "method": "ipc.signal",
  "params": {
    "kind": "turn:end",
    "sessionId": "7f6b2bc1-27b2-4052-a2b7-de05d2538178",
    "turnId": "999068c5-c52b-4ccd-a936-682bea162657",
    "usage": {
      "input": 10,
      "output": 33,
      "modelId": "mock",
      "timeToFirstTokenMs": 2,
      "streamDurationMs": 2
    },
    "$seq": 42
  }
}

{
  "jsonrpc": "2.0",
  "method": "ipc.signal",
  "params": {
    "kind": "run:end",
    "sessionId": "7f6b2bc1-27b2-4052-a2b7-de05d2538178",
    "runId": "6f577015-ffbf-4204-ba81-320f71e76f46",
    "ok": true,
    "$seq": 45
  }
}

{
  "jsonrpc": "2.0",
  "method": "ipc.signal",
  "params": {
    "kind": "presence:changed",
    "sessions": [
      {
        "sessionId": "7f6b2bc1-27b2-4052-a2b7-de05d2538178",
        "windows": 1,
        "running": true,
        "attention": false
      }
    ]
  }
}

Most signals reach every connection. Streamed command output (workspace:exec:data, workspace:exec:exit) goes only to the connection that started the command. A client ignores unknown kinds, because new kinds arrive without a version bump.

Reconnect and resume#

The server keeps the latest signals of each session (2000 signals or 4 MiB per session, 32 MiB in total). Past the total, it drops the least recently written session first. A client that kept its last handshake's signalEpoch and the last $seq it applied asks for what it missed:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "sessions.resume",
  "params": {
    "sessionId": "7f6b2bc1-27b2-4052-a2b7-de05d2538178",
    "epoch": "ed173759-2d4f-436a-b39a-36c1c969e088",
    "afterSeq": 43
  }
}

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "ok": true,
    "signals": [
      {
        "seq": 44,
        "signal": {
          "kind": "plans:snapshot",
          "sessionId": "7f6b2bc1-27b2-4052-a2b7-de05d2538178",
          "snapshot": {
            "plans": [],
            "active": null
          }
        }
      },
      {
        "seq": 45,
        "signal": {
          "kind": "run:end",
          "sessionId": "7f6b2bc1-27b2-4052-a2b7-de05d2538178",
          "runId": "6f577015-ffbf-4204-ba81-320f71e76f46",
          "ok": true
        }
      }
    ]
  }
}

The answer is { ok: false, reason } when the log cannot fill the gap. The reason is epoch (another server process, after a restart) or gap (the log dropped those signals). The client then reloads the transcript with sessions.loadEvents.

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "ok": false,
    "reason": "epoch"
  }
}

To resume without applying a signal twice:

1. Hold the live signals of the session while sessions.resume runs.
2. Apply the replay.
3. Apply the held signals that the replay did not carry.

The apps reconnect with a backoff from 1 to 30 seconds. createServerHost uses 0.5 to 15 seconds. A refused token or another server at the URL stops the retries.

Paging#

sessions.loadEvents without before or limit returns the whole transcript as an array. With either, it returns the last limit turns (default 200, at most 1000) before turn position before. Pass the cursor of the page as the next before. A page without cursor holds the first turn. A page starts on an exchange boundary, so a tool call always comes with its result. start counts the events of the transcript before the page.

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "sessions.loadEvents",
  "params": {
    "sessionId": "7f6b2bc1-27b2-4052-a2b7-de05d2538178",
    "limit": 2
  }
}

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "events": [
      {
        "kind": "user-prompt",
        "text": "Say hello.",
        "turnId": "57942b84-c9cb-42c4-be2b-79aa9fc2171e"
      },
      {
        "kind": "markdown",
        "text": "Hello from the scripted provider.",
        "streaming": false,
        "turnId": "999068c5-c52b-4ccd-a936-682bea162657"
      },
      {
        "kind": "run-summary",
        "text": "Mock · <1s · ↻1 · ↑10 ↓33 · 33000 tk/s",
        "runSummary": {
          "modelId": "mock",
          "durationMs": 10,
          "turns": 2,
          "tokensIn": 10,
          "tokensOut": 33,
          "tokensPerSecond": 33000
        },
        "turnId": "999068c5-c52b-4ccd-a936-682bea162657"
      }
    ],
    "exact": true,
    "start": 1
  }
}

A page over the message size comes back as ResponseTooLarge. If that happens, ask again with a smaller limit. sessions.getTurns pages the raw turns the same way (from, limit).

Errors#

Errors are JSON-RPC error objects. A handler that throws becomes HandlerFailed with its message:

{
  "jsonrpc": "2.0",
  "id": 13,
  "error": {
    "code": -32014,
    "message": "Session \"no-such-session\" not found. Create the session before sending a prompt."
  }
}

{
  "jsonrpc": "2.0",
  "id": 11,
  "error": {
    "code": -32601,
    "message": "Unknown method \"sessions.nope\"."
  }
}

{
  "jsonrpc": "2.0",
  "id": 12,
  "error": {
    "code": -32602,
    "message": "params must be an object."
  }
}

{
  "jsonrpc": "2.0",
  "id": 15,
  "error": {
    "code": -32040,
    "message": "\"machine.register\" needs a machine connection (a machine-scoped token); this is a client connection."
  }
}

Constants#

Methods#

Grouped by the part before the dot. Params and result are the method map's TypeScript types, exported from zidane/ipc.

chat#

sessions#

runtime#

environments#

artifacts#

history#

plans#

orchestration#

commands#

agents#

completions#

The extensions' composer completions, run on the server: the triggers a folder offers, a provider's items, and the submit hooks on a prompt about to be sent.

interactions#

browser#

terminal#

approvals#

safelist#

The "Always allow" entries approvals saved, per project. A chat token can revoke one.

queue#

drafts#

search#

extensions#

What a folder's extensions declare in Settings: their options and action rows (extensions.actions), the actions' status probes (extensions.actionStatuses) and a run (extensions.runAction: the token needs the action's own scope, admin unless the extension lowers it; the config patch it returns is the client's to save with settings.set), and a new extension's scaffold (admin, behind allowRemoteInstalls).

rpc#

Methods of the RPC contracts that extensions register, called by protocol clients. A client's token must reach the method's scope (default chat). Events arrive on the rpc.event signal. RPC and contracts explains the contracts.

ui#

Dialogs and UI requests from extensions, routed to the client that views the session. A client answers a dialog with ui.dialog.answer and reports what it views through presence. Placements explains the routing.

references#

The extensions' text references in prose: the patterns, then the views of the keys a client found.

badges#

panels#

A folder's extension side panels, run on the server. A failing panel answers its error as content, never as a JSON-RPC error. panels.watch is counted per connection: a client calls it when it shows a panel and panels.unwatch when it hides it, and a dropped connection releases its own; panel:changed goes to the watching connections only.

palette#

A folder's extension command palette items, run on the server, watched like panels: palette.watch while the palette is open, palette.unwatch once it closes, palette:changed in between.

suggest#

settings#

prefs#

The picks a client remembers across apps, in the server's state.json.

sidebar#

The sidebar's views per space and the space on show, in the server's state.json: a web app finds them again in any browser. A client reads them (sidebar.getViews, sidebar.getSpace) and saves one when it changes (sidebar.setView, sidebar.setSpace); every client of the server shares them. The kit's view record also carries session, the id of the conversation last open in that space, which a client reopens when it switches back to the space; the server stores the record as given.

presence#

integrations#

Clients that run beside the host, such as the channels runner, register their state here. Every window gets integrations:changed when the list changes.

host#

What the server's machine can do: its OS, the tools on its PATH, the sandbox, the environment kinds and what it allows. The answer is cached for a minute; refresh: true probes again.

server#

The server's self-update: its state, the setting and the newest release seen. Any token reads it (server.update.status); turning it on or off, checking now and installing now need admin. With it off, server.update.check downloads and verifies a newer release and reports state: 'ready'; server.update.install installs it.

fs#

The folders of the server's workspace roots, for a folder picker: list them, search them by name (bounded), and create one (allowCreateFolders). Each takes a chat token. A path outside the roots is refused.

git#

A folder's git checkout, inside the server's workspace roots. The writes git.checkout, git.createBranch and git.sync need an admin token. git.clone needs a chat token, and the server refuses it while allowClone is off. A clone's progress comes as git:clone:progress signals to the connection that started it. A connection that calls git.watch gets git:refs for that folder once its refs move (a commit, a fetch, a branch switch, from any process on the server), until it calls git.unwatch or drops. git.commit reads one commit's facts, for a transcript's SHA chip.

files#

A folder's files beyond a session's workspace: search in files, what names in prose point at (files.resolvePaths, for a transcript's path chips), the project's own diagnostics (files.diagnostics runs project tools: admin), and its media. Diagnostics are cached until the files move; files.diagnosticsInvalidate drops a folder's cache so the next run checks again, and files.diagnosticsTools lists the tools and whether each runs there, for a settings list.

An <img> or <video> can't send a token, so media go over HTTP under a ticket: the client picks a random one (at least 32 URL-safe characters) and registers it with files.mediaTicket on each connection; it is good while that connection is open. GET /zidane/media?ticket=…&cwd=…&path=… serves a file of a folder in the workspace roots, &side=old or &side=new one side of its git change (the repository must lie in the roots too). Only image, video and audio types are served, with byte ranges, at most 64 MiB per response (a longer range is cut short, a larger whole file refused with 413), never sniffed into another type (X-Content-Type-Options: nosniff) and sandboxed if opened as a document. A missing or dropped ticket is 401, anything outside the roots 404.

usage#

The welcome screen's numbers over the server's session store, as the desktop app sums its own. Days are the server's local days.

auth#

auth.remove is also a sign-out: it drops one stored credential, or all of them.

A browser can't listen on a loopback port for an OAuth redirect, so a browser client signs in to an MCP server through the server: it passes redirectUri as <origin>/zidane/oauth/callback, the origin it reaches the server by. The server registers that redirect, takes the code at that address itself, and answers begin with mode: 'browser'. The client opens url and calls auth.oauth.complete with no code; it resolves once the token exchange is done. A server whose pre-registered client pins its redirect stays 'loopback': the user pastes the address of the page that failed to load (complete with input). The code is matched to the flow by its state, which is random and single-use. An MCP server's stored client registered for another redirect registers again.

catalog#

skills#

onboarding#

What the setup wizard finds on the server's machine and the providers it lists, with their custom fields (stored with auth.configure).

claudeImport#

A Claude Code setup in the server user's ~/.claude: claudeImport.detect says whether there is one, claudeImport.preview what each piece would copy and skip, and claudeImport.run imports it. The import copies commands the server will run: admin, behind allowRemoteInstalls.

mcp#

catalog.mcps rows carry each server's status: its sign-in state, its tools as last listed and its last Test. A stdio row always says where it runs (scope: host or context), and shared comes from its config. An absent shared means shared, and the mcpSharing setting wins over it. mcp.upsert writes the server user's mcps.json, or with scope: 'project' the project of cwd. An Advanced OAuth client secret goes in clientSecret. The server keeps it in its MCP credential store, never in mcps.json.

models#

decisions#

machines#

machine#