Skip to content
Docs0.9GitHubInstall

Building on itWrite a client

Write a client

Connect to the app endpoint, pair a device, list chats, send a prompt, and receive replies, in about seventy lines of JavaScript.

This page is for anyone building another client of Vendetta’s app endpointApp endpoint. The private address your devices connect to. It listens on loopback until you publish it.: a watch app, a desktop widget, a bot of your own. It covers the first hour; App protocol is the full contract.

The web client and the iPhone app are clients of the same endpoint, so anything they do, yours can.

The app plugin serves one WebSocket, /v1, on a loopback address: 127.0.0.1:8743 unless [plugins.app] listen names another. Whoever runs Vendetta publishes it with TLS, so a device connects to an address such as:

wss://workstation.example.ts.net:8743/v1

On the computer itself, ws://127.0.0.1:8743/v1 works without a proxy.

Every frame is a JSON text message. The server sends each frame of 2 KiB or more as a binary message instead: the same JSON, deflated (RFC 1951, no header). A client must handle both.

Save this as client.mjs. It needs Node 22 or newer, or Bun, and nothing else:

// A minimal client of the app endpoint. Run with Node 22+ or Bun:
//   node client.mjs wss://workstation.example.ts.net:8743/v1 PAIRING-CODE
import { inflateRawSync } from "node:zlib";
import { readFileSync, writeFileSync, existsSync } from "node:fs";

const [url, code] = process.argv.slice(2);
const saved = existsSync("device.json") ? JSON.parse(readFileSync("device.json", "utf8")) : {};
const topics = new Map();
const socket = new WebSocket(url);
socket.binaryType = "arraybuffer";

const send = (frame) => socket.send(JSON.stringify(frame));

socket.onopen = () => {
  // The first frame, within 10 seconds: a pairing code once, the token ever after.
  if (saved.token) send({ type: "hello", token: saved.token, epoch: saved.epoch, cursor: String(saved.seq ?? 0) });
  else send({ type: "pair", code, device_name: "Example client" });
};

socket.onmessage = ({ data }) => {
  // Frames of 2 KiB or more arrive binary: the JSON, raw-deflated.
  const text = typeof data === "string" ? data : inflateRawSync(Buffer.from(data)).toString();
  const frame = JSON.parse(text);
  for (const event of frame.type === "events" ? frame.events : [frame]) apply(event);
  if (frame.seq) remember({ seq: frame.seq });
};

function remember(values) {
  Object.assign(saved, values);
  writeFileSync("device.json", JSON.stringify(saved), { mode: 0o600 });
}

function apply(frame) {
  switch (frame.type) {
    case "paired": // Shown once: keep the token private.
      return remember({ token: frame.token });
    case "snapshot":
      remember({ epoch: frame.epoch });
      topics.clear();
      for (const topic of frame.topics) topics.set(topic.id, topic);
      for (const topic of topics.values()) console.log(topic.state, topic.title);
      return prompt();
    case "welcome":
      return console.log("caught up from", saved.seq);
    case "topic":
      return topics.set(frame.topic.id, frame.topic);
    case "topic_deleted":
      return topics.delete(frame.topic);
    case "message":
    case "edit":
      if (frame.message.from === "agent" && frame.message.format === "markdown")
        console.log(topics.get(frame.message.topic)?.title, "\n", frame.message.text);
      return;
    case "sent":
      return console.log("sent as", frame.id);
    case "send_failed":
      return console.log("not sent:", frame.message);
    case "error":
      return console.log("refused:", frame.code);
  }
}

// Send one prompt to the first idle chat.
function prompt() {
  const idle = [...topics.values()].find((topic) => topic.state === "idle");
  if (idle) send({ type: "send", client_id: crypto.randomUUID(), topic: idle.id, text: "What changed today?" });
}

Get a pairing code on the computer that runs Vendetta, then run the client with it:

vendetta app pair
node client.mjs wss://workstation.example.ts.net:8743/v1 CODE

The first run pairs and writes device.json. Later runs need no code:

node client.mjs wss://workstation.example.ts.net:8743/v1

In a browser, the same code works with DecompressionStream("deflate-raw") in place of node:zlib, and the token kept wherever the page keeps its secrets.

The first frame must arrive within 10 seconds, and is one of two:

Frame Reply
{"type":"pair","code":"…","device_name":"…"} {"type":"paired","device":"…","token":"…"}, then a snapshot
{"type":"hello","token":"…","epoch":"…","cursor":"…"} welcome, then the events missed, or a snapshot

A pairing code works once and lasts 10 minutes. The token is shown once; the server keeps only its SHA-256 digest. A failure replies {"type":"error","code":"unauthorized"|"pairing"|"busy"} and closes.

vendetta app devices lists paired devices, and vendetta app revoke removes one.

A snapshot carries epoch, seq, the projects as groups, the chats as topics, and recent messages. Every later change is an event with a higher seq. Several at once arrive as one events {seq, events} frame.

Keep the last epoch and seq, and send them in the next hello. The server replays what was missed, or sends a new snapshot when it restarted or its log no longer reaches the cursor. Merge a snapshot into what the client holds by message id.

Some frames carry no seq and are not replayed, such as ui, the plugins’ contributions.

The server pings every 20 seconds and closes a connection that sends nothing for 70. A WebSocket library that answers pings keeps the connection open.

Each topic is one agent’s chat:

Field Holds
id What requests name the chat by
title The agent’s name
state running, idle, question, approval, starting, unknown, or exited
group Its project
master, manager Whether it is the Master, or leads a team
muted, kept, ephemeral What the owner set on it

A topic event replaces a chat; topic_deleted removes one.

{"type":"send","client_id":"7c1f…","topic":"42","text":"What changed today?"}

client_id is the client’s own id for the message. The reply is sent {client_id, id} or send_failed {client_id, message}. An outcome {topic, id, outcome} event then says accepted or rejected; a refused message’s reason follows in a second outcome.

An accepted prompt’s receipt moves from waiting to read, or to dropped when the agent will never read it. Each change arrives as an edit.

A message the server took carries the client_id it was sent with. When a send gets no reply, reconnect and look for that id before sending the text again.

Event Means
message {message} A new message
edit {message} A full message that replaces the one with its id
progress {…} A running turn grew; see Synchronization for how to apply it
messages {messages} A chat’s history from its transcript, added at once

A message has id, topic, from (agent or owner), ts, kind, text, and format. Final replies are markdown, and nothing else is. A running turn is one progress message that the server keeps changing.

A question arrives as a message with format: "question" and buttons. Answer by pressing one:

{"type":"press","topic":"42","message":"1017","data":"…"}

data is the button’s own data, sent back unchanged. A press is accepted only for a button currently on that exact message.

  • Photos, videos, audio, and uploads: Photos, videos, and audio.
  • Starting, stopping, and resuming agents: the agents request, under Agents.
  • Schedules, tasks, and the queue: their sections in the same page.
  • Types: crates/app-wire/src/lib.rs defines every payload and generates the web client’s web/src/kit/wire.ts and the iOS kit’s Wire.swift.
  • Fixtures: fixtures/app/ holds frame sequences with the state a client must reach.
  • A scripted endpoint to develop against: bun mock/server.ts in web/.