> For the complete documentation index, see [llms.txt](https://docs.kyvvu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kyvvu.com/cli-reference/serve.md).

# 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_LOCATION` — trace flush destination (URL, `stdout`, file path, or `none`)
* `KV_LOG_FORMAT` — trace format (`kv`, `json`, or `otlp`)
* `KV_INCIDENT_LOCATION` — incident destination; unset = inherit the trace sink (`…/api/v1/incidents` for `kv`)
* `KV_INCIDENT_FORMAT` — incident format; unset = inherit `KV_LOG_FORMAT`
* `KV_POLICY_TTL_SECONDS` — policy cache TTL

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

***

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