npm package: @kya-os/compute
Description: Compute process for managed KYA-OS agents — PID 1 in Fly machines
Latest version: 0.1.1

# @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

```bash
# 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)