Skip to content

Reference

Gateway API

The local gateway's HTTP endpoints, WebSocket RPC and push events, and the method list. The Quetzal app, the web console and the Feishu channel use exactly this.

#Overview

The gateway's plain HTTP listens only on 127.0.0.1:<gateway.port> (default 7788, plus [::1]). When it is open to the LAN (gateway.lan is true, or gateway.host is not a loopback address such as 0.0.0.0), it also serves HTTPS / WSS on <gateway.host>:<gateway.lanPort> (default 7789) with exactly the same interface. The certificate is self-signed and generated by the runtime (ECDSA P-256, 10 years, secrets/gateway-tls.key / gateway-tls.crt); its fingerprint is the lowercase hex SHA-256 of the certificate DER, which native consoles pin. There is no plain HTTP on the LAN. Every control entry (app, web console, Feishu, host tools) goes through one operations layer, so they behave identically and are all audited. When web/index.html sits next to main.cjs (the web console placed there by the npm package or the Windows installer), the gateway also serves those static files.

#HTTP

MethodPathNotes
GET/health{ok, version, safeMode, mode}, no token required
GET/auth/local{ok, token}: only on the local plain listener, only for a browser on the same machine (connection from the loopback address, local Host header, local Origin if any); the web console logs in as soon as it opens. Anything else gets 403. A local process can read the token file anyway, so this does not widen the trust boundary. A connection forwarded through an ssh tunnel counts as local
GET/, /<static file>The web console (when web/ exists): unknown paths without an extension fall back to index.html; ETag supported
GET/pair/info{ok, fingerprint, short, body, version, tls: true}, no token required: the certificate fingerprint (full and the 1a2b 3c4d 5e6f 7a8b short form), body name, version
POST/pair/startGenerates an 8-character pairing code (letters and digits, valid 5 minutes; repeated requests keep the same code while it is valid, and repeated wrong guesses lock pairing for a while), delivered with the certificate's short fingerprint via adapter notification and Feishu
POST/pair/finish{proof} (or {code} on the local plain listener) → {ok, token, fingerprint}; proof = hex(PBKDF2-HMAC-SHA256(code (uppercased, spaces and dashes removed), "quetzal-pair-v2|" + the certificate fingerprint the client saw in the handshake, 100000 iterations, 32 bytes)). Over HTTPS only proof is accepted (code gets 400), so a man in the middle with another certificate cannot pair; the client then checks the returned fingerprint. 400 missing proof, 403 wrong, 410 expired or more than 5 attempts, 429 locked
POST/upload?name=&token=Upload one attachment (≤ 50 MiB) → {ok, file: {id, name, path, rel, mime, size, kind}}
GET/uploads/<rel>?token=Download an attachment (uploads directory only; documents are served as downloads with their file name)

#WebSocket /rpc?token=<token>

json
{ "id": 1, "method": "status", "params": {} }
{ "id": 1, "result": { } }
{ "id": 1, "error": { "code": "", "message": "" } }
{ "event": "state", "data": { } }

#Push events

EventData
hello{version, safeMode}
stateFull state, same as status (debounced 500 ms)
timelineNew timeline entry {id, ts, kind, title, detail}
approvalApproval {id, action, reason, args, status}
saySomething it says proactively
activityProgress {session, conv, origin, channel, ts, kind, …}; kind below
secretSecret-input state (never contains values)
canvas.changedA canvas changed {doc, conv, kind, author?} (kind: created, edited, renamed, deleted, comment, run, copied from another body)
feishu.qr / feishu.registered / feishu.errorFeishu one-tap setup

activity.kind: start / queued / steer / step / delta (streamed fragment) / text / tool (one event while running, one after) / alive (15-second heartbeat) / done / error. Every turn in progress is also kept as a snapshot (sessions.live) so a client can rebuild its UI at any time.

#Methods

Observe

MethodParamsReturns
status—{agent, version, body, adapter, heart, physical, stopped, paused, activity, usage, budget, approvals, soul, models, thought}
timeline{limit?, before?, kind?}Timeline (newest first); detail includes the process and each tool step
messages{limit?}Recent conversation
audit{limit?, action?}Audit records; action: "sentinel.review" lists only review verdicts

Converse

MethodParamsNotes
chat.send{text, conv?, turn?, attachments?, mode?}mode: steer (default, interjection) / queue / interrupt
sessions / sessions.create / sessions.rename / sessions.archive…Session management; sessions can filter by channel, in progress, pinned, project and time, and sort by last update, creation time or title (pinned sessions always come first)
sessions.pin / sessions.move{id, pinned?} / {id, project}Pin and unpin; put a session in a project or take it out
sessions.search{query, limit?}Search sessions by title and content, one best hit per session (snippet, highlight ranges, message id)
sessions.messages{id, limit?, before?, from?}One session's conversation (with process records); with from (a message id) it starts near that message (to open a search hit); in attachments, files the agent generated and attached to a reply carry by: "agent"
projects / projects.create / projects.update / projects.delete…Projects: name, description, project instructions (added to the system prompt of every session in the project), color and icon, archiving; deleting a project keeps its sessions and only removes them from it
sessions.live—Snapshots of turns in progress
poke{note?}Poke

Canvas (see the guide)

MethodParamsNotes
canvas.list / canvas.get / canvas.versions{conv?} / {id, version?} / {id}A conversation's canvases, one canvas in full (with comments and recent runs), version history
canvas.create / canvas.edit / canvas.update / canvas.delete / canvas.restore…Create; save as a new version (with base: if the agent just changed it, it is still saved and conflict is returned); rename or change language; delete; restore a version
canvas.run / canvas.runImage{id, version?, timeout?} / {run, name}Run the code in the sandbox (gated by the Run commands permission); fetch an image the run produced
canvas.comment / canvas.reply / canvas.resolve / canvas.apply…Comment on a selection (sent to the agent by default), reply, resolve, accept the agent's edit suggestion
uploads.preview{rel, max?}A light preview of an attachment: the beginning of its text (for xlsx, the first rows of each sheet); used by the file card's Preview in the console

Vault: secrets, secrets.delete, secrets.pending, secrets.end.

Speech: speech / setSpeech, speechVoices, speechTest.

Tuning and safety

MethodParams
activity{value} (0–4)
pause{paused}
personality{changes: {"tau.curiosity": 2, …}} (bounded)
stop / unstop{reason?} / —
permissions / setPermission— / {id, level: allow|review|ask|deny}
sentinel / setSentinel— / {enabled?, model?, timeoutMs?, classes?, onFailure?, hostMode?}: safety review settings, the available risk classes and review models
approvals / decide— / {id, approve, note?}
budget / setBudget— / {dailyTokens?, dailyCostUsd?, minBattery?, maxTempC?}
config / setConfig— / {timezone?, brain?, heart?}
restart—
selfUpdate—
supervision / setSupervision— / {enabled}

Memory

MethodNotes
memory / editMemory / setSoulResident memory and personality
journalList / journalJournal
notes / note / searchNotes and retrieval
soulConfig / setSoulConfig / soulKey / syncSoulSoul repository address (SSH only) and access mode sshMode (deploy / custom + sshKeyPath / system), local public key, sync now
agent / setAgentIdentity
bodiesRegistered bodies
soulHistory / soulShow / soulRevertMemory history, diff, revert

Models

MethodNotes
providers / saveProvidersRead / save as a whole (versioned; mismatch returns STALE_CONFIG)
catalog / refreshCatalog / remoteModelsModel catalog
testModel{ok, latencyMs, message}
moveModel / toggleModelGlobal order and enable/disable

Provider configuration shape:

typescript
interface Provider {
  id: string; catalogId: string; name: string; baseUrl: string; enabled: boolean;
  protocol: "openai-completions" | "openai-responses" | "anthropic-messages" | "google-generative-ai";
  keys: { id: string; label: string; lastFour: string; enabled: boolean; secret?: string }[];
  models: { id: string; name: string; enabled: boolean; context: number; maxTokens: number; sortOrder: number; cost?: { input: number; output: number } }[];
}
interface ProviderConfig { providers: Provider[]; quickModelId?: string }

Feishu: feishu.status, feishu.register, feishu.set.

This is an overview. Field-level detail is in the repository's docs/API.md; the code is authoritative.