@kya-os/compute
v0.7.3
Published
Compute process for managed KYA-OS agents — PID 1 in Fly machines
Readme
@kya-os/compute
PID 1 process for managed KYA-OS agent deployments on Fly.io. Orchestrates the full agent lifecycle: fetching configuration from Checkpoint, installing and running the OpenClaw runtime, maintaining heartbeats, and optionally connecting to the DIDComm agent fleet.
Overview
For the current outbound HTTP proof guarantees, validation and remaining integration work, see HTTP signing status.
When Checkpoint deploys a managed agent, it provisions a Fly machine using the kya-openclaw Docker image. That image runs kya-compute as PID 1 — this package. Compute is the supervisor that bridges the Checkpoint control plane with the OpenClaw agent runtime.
┌──────────────────────────────────────────────────────────┐
│ Fly Machine │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ kya-compute (PID 1) │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌─────────────────┐ │ │
│ │ │ Config │ │Heartbeat │ │ Control Server │ │ │
│ │ │ Fetcher │ │ Loop │ │ (WS :18790) │ │ │
│ │ └────┬─────┘ └────┬─────┘ └────────┬────────┘ │ │
│ │ │ │ │ │ │
│ │ ┌────▼──────────────▼─────────────────▼────────┐ │ │
│ │ │ Runtime Manager │ │ │
│ │ │ (spawns + supervises OpenClaw gateway) │ │ │
│ │ │ :18789 │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ ┌───────────────────────────┐ │ │
│ │ │ Pairing API │ │ DIDComm Sidecar (opt) │ │ │
│ │ │ (HTTP :18791)│ │ or Coordinator Hub │ │ │
│ │ └──────────────┘ └───────────────────────────┘ │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ /data (Fly Volume) — persists openclaw config, state │
└──────────────────────────────────────────────────────────┘Boot Sequence
When kya-compute starts, it runs this sequence:
- Parse environment — Validates required env vars (
AGENT_DID,CHECKPOINT_API_URL,AS_HEARTBEAT_TOKEN) - Fetch config bundle —
GET /api/v1/molti/deployments/{agentDid}/config-bundlefrom Checkpoint, with retry + exponential backoff - Kill switch check — If the agent has been revoked, exit immediately
- Install runtime — Install OpenClaw at the version specified in the config bundle (uses pre-warmed Docker image cache for fast installs)
- Configure runtime — Write
openclaw.json, channel configs, env vars, soul file via the config patcher - Start runtime — Spawn OpenClaw gateway as a child process with crash detection and auto-restart
- Start DIDComm (optional) — Connect to fleet hub as a sidecar, or start a coordinator hub
- Start heartbeat — POST status to Checkpoint every 30s, process commands (stop, restart, update_config)
- Start control server — WebSocket on
:18790pushes status + pairing events to Checkpoint dashboard - Start pairing server — HTTP on
:18791for channel pairing operations - Register signal handlers — Graceful shutdown on SIGTERM/SIGINT
Environment Variables
Required
| Variable | Description |
|---|---|
| AGENT_DID | Agent's decentralized identifier (did:key:...) |
| CHECKPOINT_API_URL | Checkpoint API base URL (e.g., https://kya.vouched.id) |
| AS_HEARTBEAT_TOKEN | Authentication token for heartbeat + config-bundle endpoints |
Optional
| Variable | Default | Description |
|---|---|---|
| DATA_DIR | /data | Persistent data directory (Fly volume mount) |
| CONTROL_PORT | 18790 | Control WebSocket server port |
| PAIRING_PORT | 18791 | Pairing HTTP server port |
| HEARTBEAT_INTERVAL_MS | 30000 | Heartbeat frequency in milliseconds |
| DIDCOMM_ROLE | (unset) | coordinator to run a hub, worker for sidecar |
| DIDCOMM_HUB_ENDPOINT | (unset) | Hub URL for sidecar mode (e.g., wss://hub.fly.dev:4000) |
| DIDCOMM_HUB_PORT | 18821 | Port for coordinator hub |
| DIDCOMM_AGENT_NAME | (derived from DID) | Human-readable agent name for fleet |
| DIDCOMM_PEERS | (unset) | Comma-separated peer agent names |
| FLEET_MCP_PORT | 3002 | Fleet MCP server port (coordinator only) |
Ports
Defined in src/fly-ports.ts. If you change these, update the Fly machine creation in Checkpoint as well.
| Port | Protocol | Purpose | Fly Public Port |
|---|---|---|---|
| 18789 | HTTP + WS | OpenClaw gateway | 443 |
| 18790 | WS | Control server (status, pairing events) | 18790 |
| 18791 | HTTP | Pairing API (approve, status) | 18791 |
Key Modules
| File | Purpose |
|---|---|
| boot.ts | Boot orchestrator — wires all modules together |
| cli.ts | Env var parsing and validation |
| config-fetcher.ts | Fetches config bundle from Checkpoint with retry logic |
| config-patcher.ts | Decomposes config bundle into openclaw.json + channel configs + env vars |
| runtime-manager.ts | Child process lifecycle — start, stop, restart, crash detection |
| heartbeat.ts | Periodic heartbeat POST + command processing |
| control-server.ts | WebSocket server pushing status to Checkpoint dashboard |
| pairing-server.ts | HTTP endpoints for channel pairing operations |
| kill-switch.ts | Signal handlers for graceful shutdown |
| bindings/openclaw.ts | OpenClaw-specific install, configure, and start logic |
| fly-ports.ts | Port constants shared with Checkpoint |
| didcomm/ | DIDComm sidecar, coordinator hub, fleet MCP server |
| pairing/ | FsPairingStore, PairingWatcher, PairingOrchestrator |
Config Bundle
The config bundle is the payload Checkpoint sends to the agent at boot (and on update_config commands). It contains everything the agent needs to run:
- OpenClaw version to install
- Gateway token for auth
- AI provider credentials (API keys for Anthropic, OpenAI, etc.)
- Model configuration (default model, thinking mode)
- Channel configurations (Telegram, Discord, Slack, WhatsApp tokens)
- Kill switch flag
- Soul/personality content
- Fleet/DIDComm settings
The schema is defined in @kya-os/contracts/compute (ConfigBundleSchema).
Heartbeat Protocol
Every 30 seconds, compute POSTs to Checkpoint:
POST /api/v1/molti/agents/{agentDid}/heartbeat
X-Heartbeat-Token: <token>
{
"status": "running",
"openclawVersion": "2026.2.26",
"machineId": "fly-machine-id",
"uptimeSeconds": 3600,
"memoryMb": 512,
"computeVersion": "0.1.0"
}Checkpoint responds with commands:
| Command | Effect |
|---|---|
| stop | Graceful shutdown (exit) |
| restart | Restart the OpenClaw gateway process |
| update_config | Re-fetch config bundle, reconfigure, restart if changed |
| update_version | (not yet implemented) |
DIDComm Integration
Compute supports two DIDComm roles:
coordinator— Starts aCoordinationHubWebSocket server that other agents connect to. Also starts a Fleet MCP server for task dispatch.worker(or unset withDIDCOMM_HUB_ENDPOINT) — Starts aDIDCommSidecarthat connects outbound to a coordinator hub.
DIDComm is optional and non-fatal — if it fails to start, the agent continues running normally.
Observer Authentication & Authorization
The coordinator hub binds 0.0.0.0, not loopback — any deployment that also runs a dashboard, a fleet-server, or an orchestrator daemon off-box exposes :18821 (default) to the network. An admitted observer receives the hub's entire cross-tenant event history and agent snapshot, unfiltered, and may send fleet.dispatch to dispatch work to any connected agent.
| Env var | Effect |
|---|---|
| DIDCOMM_OBSERVER_AUTH | loopback (default) — a loopback socket may observe unauthenticated; anything off-box must prove DID control. required — every observer proves, loopback included. off — nobody proves (only for an operator fronting the port with their own auth). |
| DIDCOMM_OBSERVER_ALLOWED_DIDS | Comma/whitespace-separated allowlist of DIDs authorized to observe, checked after DID control is proven. Unset admits any DID that proves control. |
Two things to know before relying on the defaults:
- Authentication is not authorization.
did:keyis self-certifying, soDIDCOMM_OBSERVER_AUTH=requiredalone only proves some identity connected, not that it should be trusted with cross-tenant data and dispatch access — anyone who can reach the port can mint a fresh keypair and pass. SetDIDCOMM_OBSERVER_ALLOWED_DIDSto actually restrict who is admitted. loopbackmode trustsremoteAddressalone. A reverse proxy,cloudflared, orsocatrunning on the same box makes every forwarded client look like a loopback peer, which the hub does not re-derive fromX-Forwarded-For(an attacker-controlled header on an unauthenticated connection). UseDIDCOMM_OBSERVER_AUTH=requiredfor any deployment sitting behind a reverse proxy.
Development
# Build
pnpm --filter @kya-os/compute build
# Test
pnpm --filter @kya-os/compute test
# Test with coverage
pnpm --filter @kya-os/compute test:coverageDocker Image
The production Docker image is at deployments/kya-openclaw/. See deployments/kya-openclaw/CLAUDE.md for build details, CI triggers, and version pinning.
Related
@kya-os/contracts/compute— Zod schemas for ConfigBundle, Heartbeat, ComputeCommand@kya-os/contracts/compute-binding— ComputeBinding interface (runtime abstraction)deployments/kya-openclaw/— Dockerfile + fly.toml for the production image- Checkpoint deploy pipeline —
apps/web/app/api/v1/molti/deploy/managed/fly/route.ts(in checkpoint repo)
