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

Windows: Kynver Desktop

On Windows x64 there is also Kynver Desktop, which bundles this runtime and its own Node.js, so there is no npm install and no terminal. It is offered in Account → Settings (next to these commands) only once a release is published, and a scenario is declared supported only after it has been tested end to end; until then the command line above is the way in. Only one runtime may work for a workspace on a computer: quit Desktop before running kynver start, and stop the CLI before starting Desktop.

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]
browser status | install [--deps] [--force]
agents status [--json] | setup hermes|openclaw|claude-code [--dry-run]

Run kynver help for the full flag-level usage.

Chat browser

When website chat uses the browser on your computer, Kynver picks one automatically: a path you configured, then an installed Chrome / Chromium / Edge, then its own copy. If there is none, Kynver downloads Chrome for Testing (Google's official build, about 150 MB, once) into ~/.kynver/browsers — no sudo. kynver browser status shows what will be used; kynver browser install downloads it now. On a minimal Linux or WSL install Chrome may also need system libraries: kynver browser status prints the exact apt-get / dnf command, and kynver browser install --deps runs it when sudo needs no password. On WSL the browser window appears on your Windows desktop through WSLg; without a display it runs headless. Turn the automatic download off with "browserAutoProvision": false in ~/.kynver/config.json.

Agent tabs (Hermes, OpenClaw, Claude Code)

Kynver chat can open a tab for each agent you run on this computer: your Hermes Agent, your OpenClaw agent, or your own signed-in Claude Code. The daemon talks to them on localhost and relays messages over its existing Kynver connection — nothing is exposed to the internet and their keys never leave this computer. kynver agents status shows what was found. kynver agents setup hermes switches on Hermes's local API server in ~/.hermes/.env (with a new local-only key); restart the Hermes gateway afterwards. kynver agents setup openclaw switches on the OpenClaw gateway's chat API and restarts it. Claude Code needs only claude signed in and a folder chosen for chat computer access. Steps are logged to ~/.kynver/logs/agent-tabs.jsonl (no message text); session ids per tab live in ~/.kynver/agent-tab-sessions.json. KYNVER_OPENCLAW_AGENT picks a non-default OpenClaw agent; KYNVER_AGENT_TAB_CLAUDE_MODEL pins a Claude Code model (default: your own Claude Code default).

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 | Google Antigravity (agy on PATH, install) | kynver setup --provider gemini, install Google Antigravity, then run agy once to sign in. Website chat uses this same CLI — no Gemini API key. A Gemini API key works only when ~/.gemini/antigravity-cli/settings.json sets "modelProvider": "gemini" and GEMINI_API_KEY is set (still the CLI, not HTTP). Workers run agy --prompt --output-format stream-json. Set KYNVER_GEMINI_BIN=gemini only for a legacy enterprise gemini binary; that binary's website chat stays the HTTP key path. 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. |

The gemini-api HTTP route and a legacy gemini binary use KYNVER_GEMINI_DEFAULT_MODEL (default gemini-2.5-pro). Google Antigravity omits that id at spawn so agy keeps the signed-in account's model; pass an Antigravity slug such as gemini-3.1-pro-high when you want a specific one. 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). Google Antigravity boxes spawn agy in that same workspace (run agy once; a bare API key does not select HTTP). gemini-api and a legacy gemini binary still 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). A missing or signed-out agy fails closed (antigravity_cli_unavailable / antigravity_not_logged_in) — no silent hosted-model 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.