@kynver-app/runtime

Standalone Kynver AgentOS execution runtime and CLI (kynver) — run Kynver's agent harness on your own machine, on your own provider subscriptions. Provider credentials stay local to the box; the daemon talks to Kynver over scoped, revocable krc1.* runner tokens.

Requirements

• Node.js 24.11.0+ (npm 11). This is a hard engine floor: below it the CLI fails closed at startup — every work-executing command refuses to run, and only --version and the doctor diagnostic commands stay reachable for diagnosis. Check any host with:

  kynver doctor node-runtime   # report-only JSON classification + remediation

• A worker-provider CLI on PATH with an active login/subscription (see Worker providers).

• Agentic OS access on your Kynver account. Access is admin-approved: if kynver bootstrap reports that your account has no access, request it at https://www.kynver.com/agent-os/early-access — once approved, your account works here with no further changes (just re-run kynver bootstrap).

Quick start

npm install -g @kynver-app/runtime
kynver bootstrap --api-base-url https://www.kynver.com
kynver start

That is the whole golden path: bootstrap links this machine to your account and workspace; start brings the agent online (keeper-supervised daemon — Ctrl-C stops it). For a persistent background agent on Linux: kynver start --install-systemd.

What kynver bootstrap does

1. Device login — prints a URL and a short code; approve in the browser. No API-key pasting; the minted key is saved to ~/.kynver/credentials.
2. Workspace resolution — resolves your account's primary AgentOS workspace. If the account is not approved for Agentic OS yet, bootstrap says so and links the request page (see Requirements above).
3. Machine setup — persists ~/.kynver/config.json (API base URL, workspace id, repo discovery, worker caps, box identity) and mints a scoped krc1.* runner credential.

Bootstrap does not start any work — bringing workers online is kynver start.

Troubleshooting → kynver doctor runner-install

If bootstrap or start fails, or the agent seems dead:

kynver doctor runner-install

It walks the whole first-run lifecycle — install, device login, workspace binding, repo selection, runner credential, daemon liveness — plus the first-run blockers: worker-provider CLI on PATH, boxKind identity, repo base ref (origin/main / remote default branch), and live API reachability/auth (a 401 means a revoked key → kynver login; a 403 means access is gated → request it at the early-access page). Every failing check carries the exact command that fixes it.

Report a bug

`kynver report-bug` prepares a draft locally — it does not send anything. After you create a GitHub issue, the report appears at github.com/Totalsolutionsync/kynver-feedback/issues.

```bash kynver report-bug --json # agents: read submission.autoSubmit (false) and guide.agentSteps ```

Install/runtime → install template. Other product bugs → product template. Guide: kynver.com/help/bug-reports.

Callback auth (scoped runner tokens)

User-hosted runners should not use deployment-wide OPENCLAW_CRON_SECRET / KYNVER_RUNTIME_SECRET. kynver bootstrap mints a workspace-bound token automatically; to re-mint one:

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 are accepted on by-id callbacks only when the deployment lists the workspace in KYNVER_HARNESS_GLOBAL_SECRET_AGENT_OS_IDS (first-party dogfood). Self-serve runners must use scoped krc1.* tokens. QStash-signed scheduler callbacks and internal cron fire routes are unchanged.

CLI verbs

bootstrap | start | status | setup | login | daemon
run create | list | status | dispatch | sweep
worker start | status | tail | stop | complete
runner credential [mint|status|list|revoke|rotate]
config ensure-default-repo
doctor runner-install | node-runtime | local-store | context-envelope | runtime-takeover
report-bug [--json] [--message TEXT] [--skip-doctor]

Run kynver help for the full flag-level usage.

Worker providers

Set once in kynver setup --provider claude|cursor|codex|gemini|gemini-api|openai-compatible (stored in ~/.kynver/config.json as workerProvider). --provider chatgpt / gpt are aliases for codex.

| Provider | CLI / endpoint | Auth | | --- | --- | --- | | cursor (default) | agent on PATH (Cursor Agent CLI) | agent login (OAuth) or CURSOR_API_KEY for headless runners. Website chat uses this same CLI when workerProvider/chatProvider is cursor — agent on PATH + agent login (or CURSOR_API_KEY). Missing/logged-out fails closed (no hosted-model fallback). | | codex (ChatGPT on your machine) | codex on PATH (Codex CLI) or hermes with openai-codex | codex login / CODEX_API_KEY, or hermes auth status openai-codex. Website chat uses this same CLI when workerProvider/chatProvider is chatgpt / codex / gpt — missing/logged-out fails closed (no hosted-model or Claude fallback). You do not need OPENAI_API_KEY for this path. Workers also spawn codex exec. When the standalone codex CLI is absent, harness workers can fall back to hermes openai-codex. | | 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. | | gemini | gemini on PATH (Gemini CLI) | gemini login or GEMINI_API_KEY (allowlisted through the worker-env scrub, same as CODEX_API_KEY). Missing binary fails closed. | | gemini-api | Google Gemini over HTTP (no local CLI). Default https://generativelanguage.googleapis.com/v1beta/openai | KYNVER_GEMINI_API_KEY or GEMINI_API_KEY — read in the daemon parent and handed to the runner over stdin, never argv/child env. Override the endpoint with KYNVER_GEMINI_BASE_URL. | | openai-compatible (aliases openai, openai-api) | Any OpenAI-compatible /v1 chat-completions URL | KYNVER_WORKER_BASE_URL (required) + optional KYNVER_WORKER_API_KEY over stdin. This is the generic HTTP path — not the ChatGPT product option. |

Both Gemini routes share KYNVER_GEMINI_DEFAULT_MODEL (default gemini-2.5-pro). Choose the route explicitly: --provider gemini vs --provider gemini-api, or executorRef: provider:gemini[:model] / provider:gemini-api[:model]. ChatGPT on a box: --provider chatgpt or --provider codex (same Codex CLI), or executorRef: provider:chatgpt[:model].

Override per invocation: kynver worker start ... --provider gemini (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.

Website chat (delegated turns claimed by kynver daemon) follows chatProvider if set, otherwise workerProvider. Cursor boxes spawn agent --print --mode agent by default in ~/.kynver/chat-workspace (created empty — no monorepo clone, no defaultRepo assumption). ChatGPT boxes spawn codex exec --json in that same workspace (codex login or CODEX_API_KEY). Gemini boxes call Google over HTTP (GEMINI_API_KEY / KYNVER_GEMINI_API_KEY). A missing Codex CLI / login fails closed (codex_cli_unavailable / codex_not_logged_in) — no silent Claude fallback. Ask mode is only used when the website toggle requests it. The hosted personal-agent loop handles Agent-mode / factory turns so MEMBER users can call factory tools. Claude/Anthropic boxes keep the local Anthropic Messages path (ANTHROPIC_API_KEY or kynver start --chat-oauth). Command turns are unchanged (allowlist + auth proof).

Contributing

Development against a Kynver monorepo checkout is documented for contributors inside the Kynver repository.

Bug reports: see Report a bug above.