Orbtile
Download
For developers v1.2 ยท 0.3.4

Connect your own agent

Orbtile 0.3.4 brings the local Adapter API to v1.2: an adapter can send its own icon and set its own colour per state with palette.states; Error always stays red. Optional keypad events (taps, approval decisions and question answers) arrived in 0.2.1, and existing v1 adapters keep working.

Read the protocol reference
On this page
Overview

What is an adapter?

v1.2

An adapter connects an AI coding agent or tool to Orbtile so its sessions appear on the keypad and in the Orbtile panel. 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.
  • Icon: An installed app's icon (appBundleId, on a Mac) or a square PNG, 16 to 256 px and at most 32 KB, sent as base64. The PNG works on Windows too; on a Mac, an installed app's icon wins.
  • State colours: palette.states gives each state its own #rrggbb colour. thinking also colours tool use and streaming, and waitingPermission also colours questions, unless you set those states too. Error always stays red, and with One alarm colour for all agents on (Settings > Appearance), waiting keys use the shared terracotta. One adapter covers every state, so a session keeps its key when its state changes. From Orbtile 0.3.9, with Colour keys by State (Settings > Appearance), every agent, adapters included, uses your four State colours instead.

Guide: Get notified when Claude Code needs approval or finishes

Guide: Show any script or agent on a keypad with the Orbtile Adapter API

Guide: Build your own status display with Claude Code hooks

Optional keypad interaction
New in 0.2.1

Optional keypad interaction

Opt-in

Adapters can declare tap, approval and question capabilities. Once you allow the adapter in Settings > Agents, the keypad can answer the approvals and questions it declares. There is no separate Keypad switch.

  • Taps: Receive a tap and optionally open the registered URL or app. The user's tap preference still applies.
  • Approvals and questions: Hold Allow or press Deny for a pending approval; pick question options, including multiple choices, and hold Send.
  • Adapter-owned prompts: Your adapter opens the event channel, checks each request against its current on-screen dialog, applies it once and acknowledges it. Queuing a decision does not prove the adapter executed it. Its own dialog remains usable after a timeout or disconnect; neither means implicit Allow.
  • Reconnects: Sequences and acknowledgements allow unacknowledged events to replay during a live registration. Restart, unregister, token regeneration or 60 seconds of silence ends that registration and its in-memory events.
Local connection only
Transport

Local connection only

Local only

On a Mac the Adapter API is a Unix-domain socket; on Windows it listens on 127.0.0.1. Neither is reachable from the network. Adapter sessions also show on a connected Orbtile Mobile, over your local network.

Architecture

  • Local transport: No cloud relay. Adapter events travel over the local socket on a Mac or 127.0.0.1 on Windows and are never sent to our servers; Orbtile's usage summary includes only a few numbers about adapters (whether the Adapter API is on, how many adapters are allowed or turned off, how many sessions they had, how many minutes they were busy and how many adapter requests were rejected), 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 registration, session updates, heartbeats and adapter-opened event polls. The discovery file names the socket or port and the Bearer token. Interactive registrations also return an owner token. Keep both private.
A session in a few lines
SDKs

A session in a few lines

v0.2.0

The dependency-free @orbtile/adapter (Node 20+, ESM with TypeScript types) and orbtile-adapter (Python 3.10+) packages are on npm and PyPI, version 0.2.0, MIT licence. Install with npm install @orbtile/adapter or python3 -m pip install orbtile-adapter. They use the local v1.2 protocol, renew registration leases and support events with explicit acknowledgement. Version 0.2.0 adds the optional icon and palette.states registration fields; Orbtile versions before 0.3.4 ignore them. Enable the Adapter API and allow your adapter in Orbtile first.

Node

import { AdapterClient } from '@orbtile/adapter';
const client = new AdapterClient({
  adapterId: 'dev.example.agent',
  registration: { name: 'Tiny agent', palette: { baseHue: 150 } }
});
await client.connect();
await client.upsertSession('run', { title: 'Hello', activity: 'thinking' });
// Keep the client open while your agent works.
await client.unregister();
client.close();

Python

from orbtile_adapter import Client
registration = {"name": "Tiny agent", "palette": {"baseHue": 150}}
with Client("dev.example.agent", registration) as client:
    client.upsert_session("run", title="Hello", activity="thinking")
    # Run your agent here; the context renews its lease.

The SDK READMEs on npm, PyPI and in github.com/Orbtile/orbtile-adapters include interactive examples.

Specification & Guides
Documentation

Specification & Guides

v1.2

The v1.2 reference, JSON schema and working examples are available below. The Python example demonstrates the new events; shell and Node examples keep the original display-only behaviour. The owner token protects an occupied live registration. It is not persistent adapter identity: descriptor matching is not identity authentication, and a process running as you with the discovery token can register an unoccupied id.

  • The open-source adapter kit on GitHub is MIT licensed and includes the protocol, schema, shell, Python and Node reference adapters, and tests.
  • Protocol v1.2 reference: discovery, owner-token leases, opt-in decisions, replay, 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, reconcile the adapter's own dialog and publish fresh pending request ids. Mock server (its explicit --events mode simulates taps, Deny and a question answer without executing a command) and example guide let you try it locally.

Have an agent or tool you would like to connect? Write to hello@orbtile.com.