@kynver-app/runtime

Standalone Kynver AgentOS execution runtime and CLI (kynver).

Quick start

npm run kynver:build
npm run kynver -- setup --api-base-url http://localhost:3000 --agent-os-id <id> [--repo /path/to/repo] --max-workers 13
npm run kynver -- login --api-key "$KYNVER_API_KEY"
npm run kynver -- runner credential --agent-os-id <id>
npm run kynver -- config ensure-default-repo   # persist defaultRepo in ~/.kynver/config.json
npm run kynver -- run create [--repo /path/to/repo] --name my-run
npm run kynver -- daemon --run <runId> --agent-os-id <id> --execute

Callback auth (scoped runner tokens)

User-hosted runners should not use deployment-wide OPENCLAW_CRON_SECRET / KYNVER_RUNTIME_SECRET. After kynver login, mint a workspace-bound token:

kynver runner credential --agent-os-id <id>

The token (krc1.*) is stored in ~/.kynver/credentials as runnerToken and sent as X-Kynver-Runner-Token on dispatch/sweep/completion/progress callbacks. It is bound to one agentOsId and a capability set (tasks, harness, plans.progress, runtime.read, operator). The server persists only a token hash plus audit metadata, so credentials can be listed, revoked, and rotated without exposing the clear token again.

Global env secrets remain supported for first-party dogfood, QStash, and OpenClaw cron — server-side verifyHarnessCallback accepts QStash signatures, scoped tokens, or global secrets (in that precedence for non-QStash callers).

CLI verbs

run create | list | status | dispatch | sweep
worker start | status | tail | stop | complete
login | runner credential | setup | config ensure-default-repo | doctor runtime-takeover | daemon

scripts/opus-harness.mjs is a compatibility shim that delegates to this package.

Worker providers

Set once in kynver setup --provider claude|cursor (stored in ~/.kynver/config.json as workerProvider).

| Provider | CLI | Auth | | --- | --- | --- | | cursor (default) | agent on PATH (Cursor Agent CLI) | agent login (OAuth) or CURSOR_API_KEY for headless runners. | | codex (BYO OAuth / Hermes subscription, low-cost orchestration) | codex on PATH (Codex CLI) or hermes with openai-codex | codex login / CODEX_API_KEY, or hermes auth status openai-codex (ChatGPT Codex subscription). When the standalone codex CLI is absent, harness workers spawn hermes chat -q … --provider openai-codex -Q (non-interactive). Kynver never stores raw OAuth tokens — fingerprint audit only. Low-risk orchestration routes here when bound; privileged actions escalate to Cursor. | | claude (operator override) | claude on PATH | claude login (OAuth). Use --provider claude on dispatch/worker start, or set executorRef: provider:claude / [worker-provider: claude] on the board task. Legacy workerProvider: "claude" in config is normalized to Cursor at dispatch. |

Override per invocation: kynver worker start ... --provider claude (requires operator intent; default dispatches stay on Cursor)

Install Cursor CLI (Windows PowerShell): irm 'https://cursor.com/install?win32=true' | iex

Default Cursor model: composer-2.5. Override with --model on dispatch/worker start.

Targeted dispatch (after creating a board task)

Broad lane:any dispatch still sweeps the ready queue (review lane first, then priority/age). To start one specific task you just created — without admitting an older ready row — pass the task id:

kynver run dispatch --run <runId> --agent-os-id <id> --execute \
  --target-task-id <taskId> --max-starts 1

The server dispatch-next body field is targetTaskId (same semantics). When set, no candidate pages are scanned; the response includes targetTaskMiss: true if the row is missing or belongs to another workspace.

PR-ready handoff

ensurePrReadyHandoff resolves owner/repo from git remote get-url origin via URL parsing (repo names with dots, e.g. Totalsolutionsync/Kynver, are no longer truncated).

Tests

npm run kynver:test