Orbtile · Adapter Protocol v1

Overview

What is an adapter?

v1

An adapter connects an AI coding agent or tool to Orbtile so its sessions appear on the keypad and in the Mac menu. Turn on Adapter API in Settings > Agents, then allow each adapter. New adapters stay hidden until you allow them.

How adapters work

Session state: Reports whether the agent is thinking, running a tool, writing output, idle, waiting for input, or in an error state.
Tool motion: Optional toolKind selects shell, edit, read, web, delegate, plan, integration or other motion. Without a kind, the key uses other motion.
Live text: Streams the assistant's latest words directly onto the LCD key as they generate.
Attention & alarm: Triggers the agent's alarm colour when user attention or permission is needed.
Session identity: Assigns a session name, active model, and subagent count.

Transport

Local Unix-Domain Socket

Local socket

The transport is a local Unix-domain socket. All communication stays strictly on your Mac.

Architecture

Local transport: No cloud relay. Adapter events travel over a local Unix-domain socket on your filesystem and are never sent to our servers; Orbtile's daily usage report includes only three numbers about adapters: how many are allowed, how many sessions they had and how many minutes they were busy, never their names, ids or events.
Low latency: State updates and live text arrive locally, without a cloud relay.
Simple protocol: HTTP/1.1 and JSON for adapter registration, session updates and heartbeats. The discovery file names the socket and token. Keep the token private.

Documentation

Specification & Guides

v1

The v1 reference, JSON schema and working reference adapters are available below. Taps can open a session through its registered URL scheme or application. Third-party adapters cannot receive keypad answers or approval decisions in 0.2.

Protocol v1 reference: discovery, authentication, endpoints, limits and retry rules.
JSON schema and reference adapters: shell + curl, Python stdlib, Node 18+.
Send a heartbeat at least every 10 seconds while sessions are live. After a relaunch or token change, rediscover, register again and resend the whole session. Mock server and example guide let you try it locally.