kyvvu serve

What you'll learn: How to run a local policy evaluation server for non-Python agents.

---

Usage

Usage: kyvvu serve [OPTIONS]

Options:
  --host TEXT       Bind address (default: 127.0.0.1)
  --port INTEGER    Bind port (default: 8080)
  --api-url TEXT    Kyvvu platform API URL
  --api-key TEXT    Bearer API key
  --agent-key TEXT  Agent key for policy fetch

What it does

Starts a local HTTP server that wraps the kyvvu-engine. Non-Python agents (JavaScript, Go, Rust, etc.) can call this server to evaluate steps, record history, and end tasks — same engine, same policies, same sub-millisecond evaluation.

Prerequisites

Requires uvicorn and fastapi. These are included when you install the engine with serve extras:

pip install "kyvvu-engine[serve]"

Or install the full SDK (which includes everything):

pip install kyvvu

Starting the server

$ export KV_API_URL=https://platform.kyvvu.com
$ export KV_API_KEY=KvKey-...
$ export KV_AGENT_KEY=my-agent
$ kyvvu serve
kyvvu serve — policy evaluation server
  API:       https://platform.kyvvu.com
  Agent:     my-agent
  Endpoints: http://127.0.0.1:8080/evaluate, /record, /end_task, /health

Or with explicit flags:

kyvvu serve --host 0.0.0.0 --port 9090 \
  --api-url https://platform.kyvvu.com \
  --api-key KvKey-... \
  --agent-key my-agent

Endpoints

Method	Path	Purpose
GET	/health	Liveness probe — returns policy count, last fetch time, TTL remaining.
POST	/evaluate	Preflight evaluation of an intended behaviour. Returns {action, risk_score, policies, blocked}.
POST	/record	Record a completed step. Returns {step, task_id}.
POST	/end_task	Close a task — evict history and flush logs. Returns {status, task_id}.
POST	/register_agent	Evaluate agent-registration policies.

See REST API (Non-Python) for full request/response examples.

Configuration

All KV_* environment variables work identically to KyvvuRunner:

• KV_API_URL — platform API URL

• KV_API_KEY — bearer API key

• KV_AGENT_KEY — agent key for policy fetch

• KV_LOG_LOCATION — log flush destination (URL, stdout, file path, or none)

• KV_INCIDENT_ENDPOINT — incident webhook destination

• KV_POLICY_TTL_SECONDS — policy cache TTL

The server also reads ~/.kyvvu/config.toml (populated by kyvvu login).

---

Next steps

• REST API (Non-Python) — integration guide with curl examples

• Configuration Reference — all environment variables

• Architecture — why in-process evaluation is preferred over remote