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

```bash
pip install "kyvvu-engine[serve]"
```

Or install the full SDK (which includes everything):

```bash
pip install kyvvu
```

## Starting the server

```bash
$ 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:

```bash
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)](/integrations/rest-api.md) 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_ENDPOINT` — log flush destination (`stdout` by default)
* `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)](/integrations/rest-api.md) — integration guide with curl examples
* [Configuration Reference](/deployment/configuration.md) — all environment variables
* [Architecture](/core-concepts/architecture.md) — why in-process evaluation is preferred over remote


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kyvvu.com/cli-reference/serve.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.