@kya-os/compute

PID 1 process for managed KYA-OS agent deployments on Fly.io. Orchestrates the full agent lifecycle: fetching configuration from Checkpoint (AgentShield), installing and running the OpenClaw runtime, maintaining heartbeats, and optionally connecting to the DIDComm agent fleet.

Overview

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:

1. Parse environment — Validates required env vars (AGENT_DID, AGENTSHIELD_API_URL, AS_HEARTBEAT_TOKEN)
2. Fetch config bundle — GET /api/v1/molti/deployments/{agentDid}/config-bundle from Checkpoint, with retry + exponential backoff
3. Kill switch check — If the agent has been revoked, exit immediately
4. Install runtime — Install OpenClaw at the version specified in the config bundle (uses pre-warmed Docker image cache for fast installs)
5. Configure runtime — Write openclaw.json, channel configs, env vars, soul file via the config patcher
6. Start runtime — Spawn OpenClaw gateway as a child process with crash detection and auto-restart
7. Start DIDComm (optional) — Connect to fleet hub as a sidecar, or start a coordinator hub
8. Start heartbeat — POST status to Checkpoint every 30s, process commands (stop, restart, update_config)
9. Start control server — WebSocket on :18790 pushes status + pairing events to Checkpoint dashboard
10. Start pairing server — HTTP on :18791 for channel pairing operations
11. Register signal handlers — Graceful shutdown on SIGTERM/SIGINT

Environment Variables

Required

| Variable | Description | |---|---| | AGENT_DID | Agent's decentralized identifier (did:key:...) | | AGENTSHIELD_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 a CoordinationHub WebSocket server that other agents connect to. Also starts a Fleet MCP server for task dispatch.
• worker (or unset with DIDCOMM_HUB_ENDPOINT) — Starts a DIDCommSidecar that connects outbound to a coordinator hub.

DIDComm is optional and non-fatal — if it fails to start, the agent continues running normally.

Development

# Build
pnpm --filter @kya-os/compute build

# Test
pnpm --filter @kya-os/compute test

# Test with coverage
pnpm --filter @kya-os/compute test:coverage

Docker 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)