Session-persistent protocol for AI agent communication. Zero session loss across container migrations, network changes, and compute transitions.
"The internet went stateless for scale. That was right for document delivery. It's wrong for interactive AI agent sessions."
ClawTerm is the transport foundation of ClawForge — a purpose-built binary protocol for connecting terminal clients to AI agent pods running in Kubernetes. Session identity is first-class: a customer's conversation survives any infrastructure event.
Domains: clawterm.net · clawroam.com
ClawTerm is a stateful binary session protocol, TCP port 7220 (QUIC port 7221). Key properties:
- Protocol-native SUSPEND/RESUME — sessions survive any network interruption, mobile disconnect, or client restart
- Multi-device — suspend on laptop, resume on phone; same session, zero context loss
- 15-byte frame header — HDLC-inspired binary, orders of magnitude lower overhead than HTTP/WebSocket
- Pod IPC — Unix socket to agent pods on the same K8s node (zero network hop)
- inotify pod registry — automatic agent pod discovery, no polling
- 10K+ sessions per node — single epoll loop, no threads, no GC
The daemon is clawtermd: a tight C implementation (epoll, single thread, no runtime) deployed as a Kubernetes DaemonSet.
ClawRoam is the compute roaming layer of the Claw platform. It enables transparent migration of active AI agent sessions between compute nodes — geographically, for load balancing, or for node maintenance — with zero session interruption.
ClawRoam is directly inspired by ANSI IS-41 cellular network roaming (the protocol behind "your call follows you between towers"). The core insight from IS-41, applied to containers:
The target container must be warm and ready before the source releases the client.
No kill-and-restart. No session gap. The target node pre-loads conversation context, starts the agent pod, confirms readiness — and only then does the source redirect the client.
- Internet-Draft:
rfc/draft-whiddon-clawterm-compute-roaming-00.md - xml2rfc v3:
rfc/draft-whiddon-clawterm-compute-roaming-00.xml
See protocol/SPEC.md for the full wire format specification.
Bytes 0-1 Magic (0x43 0x4C)
Byte 2 Frame type
Bytes 3-6 Session ID (uint32)
Bytes 7-10 Sequence number (uint32)
Bytes 11-12 Payload length (uint16)
Bytes 13-14 CRC-16
[Payload]
| Code | Name | Purpose |
|---|---|---|
| 0x01 | CT_CONNECT | Establish session |
| 0x03 | CT_DATA | Application data |
| 0x04 | CT_SUSPEND | Client disconnecting (session preserved) |
| 0x05 | CT_RESUME | Client reconnecting to suspended session |
| 0x50 | CT_TYPE_ROAM | ClawRoam migration control |
┌─────────────────┐ ClawTerm (TCP:7220 / QUIC:7221)
│ Terminal Client │◄────────────────────────────────────────────┐
└─────────────────┘ │
│
┌─────────────────────────────────────────────────┐ │
│ KEEPER (Soul Store / HLR) │ │
│ session registry · roam controller · node map │ │
└──────────────────┬──────────────────────────────┘ │
│ │
┌────────▼───────────────────────────┐ │
│ clawtermd (DaemonSet, one per node) │─────┘
│ ┌─────────────────────────────────┐ │
│ │ epoll I/O multiplexer │ │
│ │ session table (hash map) │ │
│ │ outbound ring buffer (replay) │ │
│ │ inotify pod registry │ │
│ │ ClawRoam migration state machine │ │
│ └──────────────┬──────────────────┘ │
└─────────────────┼────────────────────┘
│ Unix socket
┌─────────────────▼────────────────────┐
│ Agent Pod (K8s) │
│ /run/claw/sockets/{tenant}_{agent} │
└──────────────────────────────────────┘
Full platform architecture: docs/ARCHITECTURE.md
make # native x86_64 build
make arm64 # cross-compile for ARM64
make docker # build Docker container imageRequires gcc, make. No external library dependencies beyond libc.
./clawtermd -p 7220 -s /run/claw/sockets -l https://keeper.deeptxai.com -t <node-token>kubectl apply -f k8s/daemonset.yamlSee docs/DEPLOYMENT.md for the full deployment guide.
Deployed: clawtermd running on lobster-1 K3s cluster, port 7220.
Host: 192.168.0.49
Port: 7220 (TCP)
Status: Listening
- Protocol spec (
protocol/SPEC.md) - Frame encode/decode (CRC-16)
- Session table (hash map, ring buffer, SUSPEND/RESUME)
- Pod IPC (Unix socket, length-prefixed, inotify registry)
- TCP server (epoll event loop, accept, dispatch)
- K8s DaemonSet manifest
- ClawRoam RFC (
rfc/) - Deployed on lobster-1 K3s
- QUIC transport (Phase 4)
- Keeper session registry service
- ClawRoam migration state machine in clawtermd
- TLS 1.3 on TCP path
- Client library (C + Node.js bindings)
- xterm.js WebSocket bridge
clawterm/
├── include/
│ └── clawterm.h — all types, constants, function declarations
├── src/
│ ├── main.c — entry point, CLI args, signal handling
│ ├── server.c — epoll event loop, TCP listener, frame dispatch
│ ├── session.c — session table, SUSPEND/RESUME, ring buffer
│ ├── frame.c — frame encode/decode, CRC16
│ └── pod_iface.c — Unix socket IPC to agent pods, inotify registry
├── k8s/
│ └── daemonset.yaml — K8s DaemonSet + Namespace
├── protocol/
│ └── SPEC.md — wire format specification
├── rfc/
│ ├── draft-whiddon-clawterm-compute-roaming-00.md — ClawRoam RFC (Markdown)
│ └── draft-whiddon-clawterm-compute-roaming-00.xml — ClawRoam RFC (xml2rfc v3)
├── docs/
│ ├── ARCHITECTURE.md — full platform architecture
│ ├── DEPLOYMENT.md — deployment guide
│ └── PROVISIONAL-PATENT-CLAIMS.md — patent draft (attorney review)
├── Makefile
├── Dockerfile — distroless, ~2MB image
└── README.md
| WebSocket | ClawTerm | |
|---|---|---|
| Session persistence | App-layer only | Protocol-native |
| Mobile disconnect | Session dies | SUSPEND/RESUME |
| Multi-device | New session | Resume from anywhere |
| Frame overhead | 200+ byte HTTP headers | 15 bytes |
| Concurrency | Thread/goroutine per conn | epoll, 10K+ sessions/core |
| Binary protocol | No (needs encoding) | Yes, native |
| Pod IPC | Network required | Unix socket, zero-hop |
| Container migration | Session dies | ClawRoam: zero-gap handoff |
MIT. See LICENSE.
Rod Whiddon · DeepTx AI · Deep East Texas rod@whiddon.net
Part of the ClawForge AI agent platform.