Skip to content
Docs0.9GitHubInstall

Running itHost protocol

Host protocol

A host gives Vendetta a terminal or multiplexer. This page is the wire contract a host serves, so one can be written in any language. Writing a host covers the plugin side: naming, config, and keys.

The host serves a Unix socket at

$XDG_RUNTIME_DIR/vendetta/hosts/<control socket's stem>-<KIND>.sock

where the control socket is the worker’s ($XDG_RUNTIME_DIR/vendetta/control/<hash>.sock, named to the plugin as VENDETTA_CONTROL_SOCKET), and KIND is the host’s kind, such as tmux or kitty. The directory is mode 0700 and the socket 0600. Every Vendetta process of the user finds hosts by listing that directory and sending hello to each socket with the right stem; a socket that does not answer is a host that is not running. A host refuses to start while another of its kind answers there, and removes a stale file.

Each connection carries any number of requests, one at a time: one JSON object per line each way, a line at most 64 MiB. Serve each connection on its own thread or task, so a popup that waits for the owner holds up nothing else.

{"method":"capture","params":{"pane":{"server":"kitty:/tmp/k.sock,4242,1731400000,b1","target":"s:w.p"},"lines":200}}
{"ok":"…text…"}
{"error":"That terminal has closed"}

A request is {"method": NAME} or {"method": NAME, "params": {...}}. The answer is {"ok": VALUE} (null for methods that return nothing) or {"error": MESSAGE}. An unknown method or malformed line answers an error and keeps the connection open.

Callers wait 10 seconds for an answer, 30 for place and create_session, and as long as it takes for popup. A connection that drops after a request was written is uncertain: the host may have acted, and nothing retries it. Refuse before acting when you can, so an error means nothing happened.

  • A server identity names one lifetime of what the host serves: KIND:ADDRESS,PID,START,BOOT, where PID is the serving process, START its start time as /proc gives it, and BOOT the kernel’s boot id. A host with nothing running answers KIND: alone. tmux identities have no prefix and start with the socket’s absolute path. Vendetta routes on the KIND: prefix and treats an identity of an ended lifetime as gone.
  • A target names a session, tab, or pane within one lifetime: session, session:window, or session:window.pane. A location is {server, target}.
  • A viewport is where the owner can look: a tmux client, a Kitty window. Its id starts with KIND: (tmux’s are client names).
  • A location of an ended lifetime, or a pane whose root process changed, is refused, never reinterpreted.
Type Shape
Location {server, target}
Pane {server, session, session_name, managed_project, attached, activity, window, window_index, window_name, window_active, id, index, active, pid, command, title, cwd, dead}. managed_project names the project when the pane sits in the Agents tab the host keeps for it, else null; pid is the pane’s root process; activity grows with use. Hosts send agents as [] or leave it out.
Session {server, id, name, cwd, attached_clients, activity}; server may be empty, as callers fill it in.
Viewport {id, pid, pane, session, session_name, window, activity, width, height, terminal, pane_tty, zoomed, hidden?}. pid is the terminal process behind it, which places it inside another host’s window; pane is the pane it shows; pane_tty that pane’s terminal; hidden that its terminal shows another tab now, as a Kitty window in a tab its OS window does not show.
Screen {text, width, height, cursor_x, cursor_y, cursor_visible}; text is the visible screen, lines joined by \n, with SGR escapes for colors and attributes.
Root {target, server, pane_pid, pane_start}
Pin {location, pid, start}: a pane pinned to the process it started with.
Input {"key": KeyPress}, {"paste": TEXT} (bracketed if the pane asked), or {"submit": TEXT} (pasted, then Enter in the same burst).
KeyPress {key, ctrl, alt, shift}; key is one character or enter, backspace, left, right, up, down, home, end, page_up, page_down, tab, backtab, delete, insert, escape, null, f1–f63.
Destination {"existing": {server, session_id}} or {"new": {name}}
LaunchReceipt {target, server_key, launch_token}; launch_token may be null.
Scope "session", "window", or "pane"
Placement {server, session, pane, project, tab, managed}; managed is whether Vendetta launched the process, when the pane’s root is exactly it, else null.
Method and params Answer
hello {kind, persistent}: persistent when panes outlive the terminal the owner closes, so a launch with no viewport makes sense.
server_key The current server identity.
panes Every pane.
sessions [server identity, [Session]], read in that lifetime.
capture {pane, lines} The last lines lines of the pane’s screen and scrollback, as text.
screen {pane, viewer_tty} Its Screen. Refuse when viewer_tty is that pane’s own terminal.
pane_viewers {pane} An opaque string naming who shows the pane; empty when none does.
input_revision {server, pane} An opaque string that changes whenever someone types into the pane.
input_revisions An opaque fingerprint of every pane’s input revision.
input {pin, input} Type into the pane. Refuse unless its root is still the pinned pid and start, checked where nothing can replace it before the write.
launch_project {destination} The project the destination names, checked against the live host.
place {cwd, destination, command} Start the argv command in a fresh pane of the project’s Agents tab; answer a LaunchReceipt.
root {location} The Root of the pane there.
viewports Every viewport, most recently used first when the host can say.
current_viewport {viewport, pid} The viewport process pid runs in, or viewport checked; null when none of this host’s. Find it from the process’s ancestry, never from inherited environment alone.
current_pane {pid} The pane id process pid runs in, or null.
graphics_pass Whether graphics drawn in a pane reach the terminal.
open {viewport, location} Show the location in the viewport; with null, make it what the host shows next.
zoom {viewport, location, zoomed} Show the pane with its tab zoomed on it (true), or with every pane laid out and it in focus.
fit {location, width, height} Size the pane alone in its tab, for a preview of that size; only a tab the host keeps for agents and no viewport shows. Hosts that cannot answer null.
create_session {name, cwd} A new project session with a shell in cwd; answer its Location.
rename {scope, location, name} Rename a session, tab, or pane title.
close {scope, location} Close a session, tab, or pane.
popup {viewport, title, command} Run the argv command floating over the viewport; answer when it exits.
native_chooser {viewport} Show the host’s own chooser.
recent_panes Pane ids the owner focused, newest first.
attach_command {location} An argv showing the location from inside another terminal, or null when panes cannot be shown elsewhere.
placement {pid, start} Where that exact process is shown, as a Placement, or null.
shortcut {window, key, action, program} A desktop-wide key for action (chooser, history, overview, master, previous, agents, layout) pressed while the desktop window of process window has focus: handle it there as the host’s own key, running the argv program, and answer true; false when that window is not the host’s.
float {command} Run the argv command floating over whatever window has focus and answer true, or false when the host cannot.

A host that cannot do something answers an error saying so, except where the table says false or null.

A host’s chooser, history, and overview keys run vendetta [--config FILE] tui, then the chooser’s own flags, in any order: --socket TMUX (the tmux server whose host it uses), --client VIEWPORT (the viewport it opens for, which it navigates), --config FILE, and --focus history (history key) or --overview (overview key). Each host builds it with vendetta_host::keys::chooser_command, and adds only what it alone knows, such as tmux’s #{q:client_name} or the Kitty window the key was pressed in.

The worker starts the host as a plugin with the usual environment (Writing a plugin). The host opens its socket, then reports report_health {"state": "running"}, and serves until the worker goes away. It exits on any panic and when a main loop stops beating, so the worker restarts it; a restart must not read as panes moving or ending, so identities stay the same while the terminal does.