vtx.foundation draft d03

VTX 1 · core · beta draft d03

VTX 1 Wire Specification: core

Oct 11, 2026, revised Nov 16, 202639 pagesALPN vtx1-d03MIT licence

§17Application interface

Applications do not speak the wire protocol. The server runs the application and talks to it in the text form: one JSON object per line, UTF-8 (JSON Lines). The server turns the application's ops into UPDATE frames and the client's input into lines for the application. A program that prints JSON, or an AI agent's tool runtime, can drive a VTX session this way. A server decides per application whether it uses this interface or runs the application under the VT engine (Section 8).

Transports.

  • stdio. The server starts the application with standard input and output as the stream; standard error goes to the server's log.
  • WebSocket. Subprotocol vtx-app1 (vtx-app1-d03 in draft d03), one line per text message, for applications that run elsewhere, such as an agent service. Which side connects, and how it authenticates (mutual TLS or a bearer token, for example), is the deployment's choice.

Lines from the application (vtx-app-1.schema.json). A line with op is a scene op (Section 7). Ops between begin and commit form one update; any other op is an update of its own. A begin without commit is discarded after 30 seconds or when the stream closes. A line without op is a control line, named by its kind (some ops, such as chart and input, have a kind prop of their own):

Kind Purpose
approval Ask the user to approve a request in the trusted zone (Section 12); answered by zone_result
permission Ask for a permission (Section 12); answered by zone_result
claim Set the name, icon and colour the trusted zone shows for the application (CLAIM)
cancel Withdraw a pending approval, permission or clipboard read by id
clipboard_write Write to the user's clipboard (Section 13)
clipboard_read Ask to read the clipboard; answered by clipboard_data
haptic Play a haptic effect on an input device (Section 11)
resource Provide a glyph or font as base64 with its format and hash; the server checks the hash, then offers and serves it (Section 10)
end End the session, with an optional exit status

Lines to the application (vtx-app-events-1.schema.json), all with kind:

Kind Carries
session attached, detached, resumed, display, caps, locale or ended, with the user, sign-in method, certificate (for x509 and tls-cert), locale, time zone, Unicode version, accepted capabilities, display and input devices as they apply
intent An INTENT, after the server has joined its parts and dropped duplicates (Section 6)
input Any other input event: event names it (key, pointer, resize and so on) and data holds the frame's payload
scene_error An op that failed: the error code with the op's state and index, or parse with the line number
zone_result The answer to an approval or permission: decision, the request digest and, for uv, the WebAuthn assertion or the card signature
clipboard_data The answer to clipboard_read, or denied

Rules.

  • The server validates every line. An invalid op is not sent and produces scene_error; so does a line that is not JSON, with code: "parse" and its line number.
  • The server numbers states, splits large updates, and handles credit, acknowledgement, retention and resume. The application sees one continuous session.
  • The server checks approval digests and assertions before zone_result reaches the application, and passes on the assertion so the application can keep it with the request and its origin (Section 12).
  • An application that closes its output ends the session as end would, without an exit status.