Termopus Docs

Architecture, API reference, and design documents

---

System Architecture

┌──────────┐         ┌─────────────────┐         ┌──────────┐         ┌────────────┐
│          │  E2E    │   Cloudflare    │  E2E    │  Bridge  │         │            │
│  Phone   │◄──────►│     Relay       │◄──────►│  Agent   │◄──────►│ Claude Code │
│          │ AES-256 │  (zero-access)  │ AES-256 │          │  stdio  │            │
└──────────┘         └─────────────────┘         └──────────┘         └────────────┘
  Flutter               CF Durable               Rust +                claude -p
  Swift/Kotlin          Objects                   Tokio              --stream-json

Data Flow

1. Pairing — Phone scans QR code containing session ID + bridge public key
2. Key Exchange — X25519 ECDH between phone's hardware key and bridge
3. Session — All messages encrypted with derived AES-256-GCM session key
4. Relay — Cloudflare forwards encrypted blobs without decryption
5. Bridge — Decrypts messages, controls Claude Code via stream-json protocol

Component Overview

Component	Language	Description
App	Flutter + Swift + Kotlin	Native mobile interface with hardware-backed security
Bridge	Rust + Tokio	Desktop agent — session management, hook system, crypto
Relay	TypeScript + CF Workers	Zero-access encrypted message forwarding
Security	Cross-platform	7-layer defense architecture
Provisioning API	TypeScript + CF Workers	Device attestation, cert signing, subscription management

Provisioning API

11 endpoints handling device lifecycle and subscriptions:

Endpoint	Purpose
POST /provision/challenge	Device attestation challenge (60s rate limit)
POST /provision/cert	CSR signing with CA private key
POST /provision/revoke	Certificate revocation
POST /provision/renew	Certificate renewal (5/hour, subscription check)
POST /provision/webhook/paddle	Paddle subscription webhooks (HMAC-SHA256)
POST /provision/check-subscription	Status check with Paddle API fallback
POST /provision/start-trial	7-day free trial (one per device, IP rate-limited)
POST /provision/restore/request	Email verification for device transfer
POST /provision/restore/verify	Code verification + subscription transfer

Claude Code Integration

The bridge communicates with Claude Code using the stream-json protocol:

claude -p \
  --output-format stream-json \
  --input-format stream-json \
  --permission-mode default \
  --model sonnet \
  --append-system-prompt "..." \
  --add-dir "$HOME"

Stream-JSON Events

Event	Direction	Description
init	Claude → Bridge	Session start with model info, capabilities
text_delta	Claude → Bridge	Streaming text output
message_delta	Claude → Bridge	Message complete with token usage
tool_use	Claude → Bridge	File edit, bash command, search, etc.
result	Claude → Bridge	Session result with cost data
user	Bridge → Claude	User message from phone

Hook Events

The bridge installs hooks in ~/.claude/settings.local.json that fire on:

Hook	Purpose
PreToolUse	Permission check before Claude acts
PostToolUse	Track completed actions
Notification	Forward notifications to phone
Stop	Session end detection

Design Documents

24+ design documents covering every subsystem:

• Session isolation and per-session encryption
• Permissions-aware hook system architecture
• Terminal mode and UI redesign
• TMux/PTY removal and stream-json migration
• HTTP tunnel for localhost development servers
• Browser screencast via Chrome DevTools Protocol
• Provisioning and subscription lifecycle
• Multi-phone relay with deduplication
• Crash recovery and session resume
• File transfer with chunked E2E encryption
• Connection status and keepalive
• Message delivery reliability
• And more...

---

termopus.com