Open Source · MIT · v1.0

Sessions that
never die.

ClawTerm is a session-persistent binary protocol for AI agent terminals. Inspired by X.25 packet switching and IBM SNA. Built in C. Runs as a Kubernetes DaemonSet. Your AI sessions survive network drops, device switches, and reboots — because the session never closes.

View on GitHub → Read the Spec

Features

What makes ClawTerm different

Every design decision exists because HTTP/WebSocket is the wrong foundation for persistent AI agent sessions.

⚡

SUSPEND / RESUME

Sessions survive any network interruption. Disconnect on laptop, reconnect on phone. Full context. Zero re-initialization. The agent never knew you left.

📦

15-Byte Frame Header

Binary wire format inspired by HDLC. FLAG + SESSION_ID + SEQ + TYPE + FLAGS + LEN. No HTTP headers. No WebSocket framing. An order of magnitude leaner.

🔌

Pod-Native IPC

Communicates with agent pods via Unix domain sockets. Zero network hop. inotify-based pod registry — new pods auto-discovered when their socket file appears.

🏗️

K8s DaemonSet

One clawtermd per node. Sessions are node-local. hostPath volume shares socket directory with agent pods. Deploys in seconds with kubectl apply.

♾️

Session Ring Buffer

256KB outbound buffer per session. On RESUME, missed frames are replayed automatically. The client picks up exactly where it left off.

🔒

TLS 1.3 + QUIC

TCP path: TLS 1.3 mandatory. QUIC path (port 7221): connection migration for mobile — change IP without dropping session. Built-in encryption, no add-ons.

Protocol Spec

Wire format

Everything on the wire. 15 bytes of overhead. Big-endian. CRC-16/IBM checksum.

clawterm wire format

// ClawTerm frame — 15 bytes fixed overhead + payload + CRC16
[FLAG:1][SESSION_ID:4BE][SEQ:4BE][TYPE:1][FLAGS:1][LEN:2BE][PAYLOAD:N][CRC16:2BE]

// FLAG is always 0x7E — deliberate HDLC homage
// All multi-byte fields are big-endian (network byte order)
// CRC covers FLAG through end of PAYLOAD

Type	Value	Direction	Description
CT_CONNECT	0x01	C→S	Establish new session
CT_ACCEPT	0x02	S→C	Session accepted, return session_id
CT_RESUME	0x03	C→S	Reconnect to existing session
CT_RESUMED	0x04	S→C	Resume ack + replay buffered frames
CT_DATA	0x10	Both	Agent I/O payload
CT_KEEPALIVE	0x20	Both	Session heartbeat (30s interval)
CT_SUSPEND	0x30	C→S	Client going away — session stays warm
CT_DISCONNECT	0x40	Both	Clean session teardown

Why ClawTerm

HTTP/WebSocket was never the right answer

HTTP is a stateless document delivery protocol. AI agents need persistent sessions. ClawTerm is built for the problem, not bolted onto a workaround.

Capability	WebSocket	ClawTerm
Session persistence	App-layer only	Protocol-native
Mobile disconnect	Session dies	SUSPEND / RESUME
Multi-device resume	New session	Any device, full context
Frame overhead	HTTP headers + framing	15 bytes
Concurrency model	Thread / goroutine per conn	epoll, 10K+ / core
Pod IPC	Network required	Unix socket, zero-hop
Mobile transport	TCP only	QUIC (connection migration)
GC pauses	Runtime-dependent	Zero (C)

Quick Start

Deploy in minutes

bash

$ git clone https://github.com/lonestar62/clawterm
$ cd clawterm
$ make
# or for ARM64 (Apple Silicon, Raspberry Pi, lobster-1)
$ make arm64

# Deploy on Kubernetes
$ kubectl apply -f k8s/daemonset.yaml

# Or run directly
$ ./clawtermd -p 7220 -s /run/claw/sockets
clawtermd v1 starting (port 7220, sockets: /run/claw/sockets)

Built into ClawForge

ClawTerm is the transport layer powering ClawForge — the customer session layer for AI agents. Deploy AI employees that know your business, with sessions that never drop.

Learn about ClawForge →

Sessions thatnever die.