> 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 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.