KoderIPC Protocol — Spec v0.1

Overview

KoderIPC is the inter-app communication protocol for the Koder Stack. It enables any Koder app — regardless of language or platform — to send and receive structured messages from other Koder apps installed on the same device.

The protocol is *anguageagnostic* any language with a socket or pipe abstraction can implement it. Languagespecific SDKs (Dart, Go, Rust, Koder Koda, etc.) are thin bindings over this spec.

Wire Format

All messages are *SONRPC 2.0*objects, newlinedelimited (\n terminates each message).

Request

{
  "jsonrpc": "2.0",
  "id": "<uuid-v4>",
  "method": "<action>",
  "params": { ... }
}

Response

{
  "jsonrpc": "2.0",
  "id": "<uuid-v4 matching request>",
  "result": { ... }
}

Error response

{
  "jsonrpc": "2.0",
  "id": "<uuid-v4>",
  "error": {
    "code": -32000,
    "message": "<human-readable>",
    "data": { "koder_error_id": "<PRODUCT-CAT-CODE-SEQ>" }
  }
}

Error codes follow JSONRPC 2.0 standard codes plus Koderdefined codes in the -32000 to -32099 range:

Notification (fireandforget, no id)

{
  "jsonrpc": "2.0",
  "method": "<event>",
  "params": { ... }
}

Transport Layer

The transport varies by platform. The message format is identical regardless of transport.

Linux desktop + CLI

• *nix domain socket* /run/user/<uid>/koder/<slug>.sock
• Created by the app at startup; removed on clean shutdown
• Permissions: 0600 (owner only)
• Multiple clients may connect simultaneously

macOS desktop + CLI

• *nix domain socket* $TMPDIR/../C/koder/<slug>.sock (sandbox-compatible path)
• Same semantics as Linux

Windows desktop + CLI

• *amed pipe* \\.\pipe\koder-<slug>
• ACL: restricted to processes signed with the Koder code-signing certificate
• Multiple clients via FILE_FLAG_OVERLAPPED + connection instances

Android

• *rimary* Explicit Intent to KoderIPCService (component name: dev.koder.<slug>/.ipc.KoderIPCService)
  • Used for oneshot fireand-forget actions
  • Message JSON passed as String extra "koder_ipc_message"
• *idirecional* AIDL Bound Service (IKoderIPC.aidl)
  • Used when the caller needs a response or ongoing interaction
  • Protected by dev.koder.permission.IPC (protectionLevel=signature)

iOS

• *RL Scheme* koder-<slug>://ipc/<action>?p=<base64-json-params>&reply=<caller-scheme>
  • reply param carries the caller's own URL scheme so the target can respond
• *pp Group shared container* group.dev.koder for file transfers and state
• One-shot only; bidirecional patterns require polling or callback URL chains

Service Discovery

An app discovers other Koder apps at runtime via platform-specific mechanisms:

Linux/macOS

ls /run/user/<uid>/koder