Kode relay

*rea:*AI
*ath:*services/ai/kode/platform
*ind:*Go backend service
*ersion:*0.4.5
*tatus:*Active — deployed at kode.koder.dev

Role in the stack

services/ai/kode/platform is the serverside hub for all Kode clients (CLI and Flutter app). It exposes a WebSocket relay at wss://kode.koder.dev/v1/relay/ws that multiplexes multiple authenticated sessions, proxies AI requests to claude CLI, and manages encrypted session persistence. It also provides a Memory Storage API for crosssession ambient context (Chronicle feature) and an unlisted public share service for read-only Kode conversations.

The relay acts as a trusted intermediary: clients authenticate with a relay token, send message frames, and receive streamed token and tool_call frames back — without ever holding AI provider credentials directly.

Primary couplings

Module	Relationship
`dev/kode`	Primary client — CLI connects via WebSocket auth+relay protocol
`services/ai/kode/app`	Flutter client — connects for relay-based AI sessions
`engines/sdk/js`	Provides `<kode-conversation>` for read-only transcript replay
`claude` CLI	Subprocess — relay calls `claude --json` for AI execution
`ai/gateway`	Alternative AI backend when `KODE_USE_GATEWAY=1`
`foundation/id`	Koder ID JWT validation for user-scoped sessions and share publishing

Interfaces

WebSocket `/v1/relay/ws`

Authentication frame: {"type":"auth","token":"...","client_id":"...","version":"..."}

Message types (client → relay):

auth — authenticate with relay token; relay replies auth_ok with session list
session_new — create session (work_dir, provider, model, custom_instructions)
session_resume — resume existing session by ID
session_delete — delete session from store
session_rename — rename session
message — send user message; relay streams token frames and tool_call frames
tool_result — return tool execution result to relay
context_snapshot — send ambient dev-environment state (git, shell, files, Chronicle PTY)
memory_save / memory_list / memory_search / memory_delete — Memory API
usage_req — request per-provider token usage stats
ping / pong — keepalive

HTTP REST `/v1/memories`

Method	Path	Description
`GET`	`/v1/memories`	List memories (filter by `work_dir`)
`POST`	`/v1/memories`	Save memory (title, content, tags, source)
`DELETE`	`/v1/memories/{id}`	Delete memory by ID
`GET`	`/v1/memories/search`	Full-text search by query

HTTP REST `/v1/relay/sessions`

Method	Path	Description
`GET`	`/v1/relay/sessions/{id}/conversation`	Read~~only session transcript JSON for `<kode~~conversation>` and Flow replay panels

Public shares

Method	Path	Description
`POST`	`/v1/shares`	Publish an authenticated Kode conversation and return an unlisted share URL
`GET`	`/v1/shares/{id}`	Return the stored public share JSON
`GET`	`/share/{id}`	Render the public read~~only conversation page with markdown, code blocks, attachments and tool calls; protected by per~~client rate limits and browser hardening headers

Health check

GET /v1/relay/health → {"status":"ok","clients":N}

Architecture

services/ai/kode/platform/
  main.go             Entry point — starts relay + REST API + optional Telegram bot
  relay_server.go     startRelayServer() — wires relay.Server with session store
  runner.go           runClaude() — executes claude subprocess, streams JSON
  session.go          sessionManager — in-memory active sessions
  api.go              REST API server (/v1

Kode Relay — WebSocket Relay, Memory & Share API