> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenovia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime

> How a request flows through the Xenovia runtime: routing, the plugin pipeline, sessions, and security.

The detail of what happens to each request, kept out of the guides. For the short version, see [How it works](https://docs.xenovia.io/how-it-works.md).

Xenovia Runtime is a Go service that speaks the OpenAI wire format and Anthropic's Messages API. It exposes four inference routes per agent and passes every inference request through a fixed pipeline before and after the upstream model call. It also serves the [Python SDK](https://docs.xenovia.io/sdk/quickstart.md)'s decision endpoint `POST /v1/execute`, which checks one stage and returns a decision without calling a model, and the hook endpoints of coding agents ([Claude Code](https://docs.xenovia.io/agents/coding-agents.md), [Codex](https://docs.xenovia.io/agents/coding-agents.md), [Cursor](https://docs.xenovia.io/agents/coding-agents.md)).

## Request flow

Before any plugin runs, the router prepares the request in this order: it validates the agent ID, checks the path and method, sets the internal `X-Xenovia-Agent-Path`, and authenticates the key. Only an authenticated request has its body read and checked (size, JSON, content modality). Then the router resolves the agent's provider, rewriting the request's `model` to the provider's configured model, and the plugin pipeline runs.

```
Request
  │  router: agent ID · path/method · authenticate key · read and check body · resolve provider + rewrite model
  ▼
  1. Auth        bind the verified identity (Redis, 5-min cache)
  2. Session     resolve or create the session UUID, set the turn number
  3. Trace       open the turn record
  4. Billing     check the organization's request allowance
  5. Enforce     hosted tool allow-list → request-stage Rego (OPA, 200 ms eval timeout)
                 → purpose gate → model_request and tool_result guardrails
  6. Failover    call the primary, or run the agent's fallback route
  │
  ▼  Upstream model (OpenAI / Anthropic / Gemini / Azure / Bedrock / Vertex / vLLM / ...)
  │
  post-hooks: response-stage Rego · model_response and tool_call guardrails · trace persist · session chain
  ▼
Response
```

> [!NOTE]
>
> The agent ID, path, and method are checked before authentication, so an unauthenticated caller can receive a `404` or `405` (or a `400` for an `X-Xenovia-Session-Id` that isn't a UUID). The body is read only after the key is verified: a `413` for an oversized body, or a `400` for invalid content, goes only to an authenticated caller. Every key that cannot act as the agent in the URL — unknown, revoked, another agent's that doesn't link it, or a deleted agent's — gets the same `401` `invalid api key for this agent`. A key of an agent that isn't active yet gets `403` `agent is not active: activate it in the Xenovia dashboard before sending requests`. A provider misconfiguration (`502`) is reported only to an authenticated caller.

A session middleware wraps the whole router and stamps `X-Xenovia-Session-Id` and `X-Xenovia-Trace-Id` into the response headers before the first body byte, so streaming responses still carry them.

## Plugin details

### 1. Auth

* Accepts `x-xenovia-key: xe_...` or `Authorization: Bearer xe_...`. On the Anthropic-compatible routes the key may also arrive as `x-api-key`, which the Anthropic SDKs send.
* Resolves the key against Redis (`apikey:{sha256(key)}`, 5-minute TTL). On a miss it calls the control plane; a resolved identity is an HMAC-signed blob holding `agent_id` and `org_id`.
* The key's agent must be the agent in the URL. The one exception is a [linked sub-agent](https://docs.xenovia.io/agents/sub-agents.md#linked-sub-agents): an agent's key may call another active agent of the same organization that it links. The call then runs as the linked agent, with the calling agent recorded as its caller. `X-Xenovia-Workflow-Id` only groups calls into a workflow; it never lets a key call another agent.
* A key scoped to an [inline sub-agent](https://docs.xenovia.io/agents/sub-agents.md#inline-sub-agents) identifies the call as that sub-agent.
* A request that still sends `x-xenovia-agent-role` is refused with `400`; use a sub-agent key instead.
* Organization keys (`ak_...`) are rejected here — they authenticate the [management API](https://docs.xenovia.io/api-reference/authentication.md), not the runtime.
* Keys are never logged; only an 8-character SHA-256 prefix appears in logs.

### 2. Session

Five strategies, first match wins:

| Priority | Source | Mechanism |
| - | - | - |
| 1 | `X-Xenovia-Session-Id` header | Must be a UUID. Anything else is rejected with `400` |
| 2 | `previous_response_id` (Responses API) | Looked up per API key |
| 3 | `user` field (Chat Completions) | Looked up per API key; the value is stored only as a SHA-256 hash |
| 4 | Message fingerprint | Hash of the messages up to the last assistant turn |
| 5 | New session | A fresh UUID |

Turn numbers increment per session (30-minute sliding TTL). Sessions are isolated per API key for strategies 2–4, and cross-organization reuse of an explicit session ID is rejected.

### 3. Trace

* Opens a turn record and emits child runs: the model call, plus policy, escalation, and runtime-executed tool runs.
* Custom `X-Xenovia-Property-*` headers are attached to the turn (see [Traces and Remediation](https://docs.xenovia.io/observability/sessions.md)).
* Persistence is asynchronous. Under sustained overload a record can be dropped rather than block the request.

### 4. Billing

There is no per-agent rate limit. The runtime checks the organization's request allowance and returns `402` when it is exhausted or billing access is restricted.

### 5. Enforce

One enforcement step runs four checks in order. A block at any of them skips the rest, and no model is called.

1. **Hosted tool allow-list.** Every hosted tool the request declares (web search, code execution, a remote MCP server, ...) must be on the agent's list when it has one.
2. **Request-stage policies.** The request-stage Rego runs against the full request context. See [Policies and Enforcement](https://docs.xenovia.io/control/policies.md) for the decision contract and the input schema. Policies are cached per agent and revalidated about every five minutes.
3. **Purpose gate.** A request made with a key scoped to an inline sub-agent is judged against that sub-agent's own capabilities. A call from an agent that links this one is also judged against the calling agent's purpose and agent-wide capabilities. See [Sub-agents](https://docs.xenovia.io/agents/sub-agents.md).
4. **Guardrails.** The `model_request` stage runs the agent's guardrails and judges the agent's own purpose, then the `tool_result` guardrails check tool results new in this request.

After the model replies, the response-stage Rego runs, then the `model_response` guardrails and a `tool_call` guardrail per proposed tool call. `memory_write` and `context_summary` guardrails run only on the decision endpoint, not on the inference routes.

Guardrails and the purpose gate are evaluated by [Neon](https://docs.xenovia.io/control/neon.md), Xenovia's decision service.

* A `block`, or a policy `escalate`, is answered with HTTP `200` and a refusal in the format of the API you called. A blocked reply or tool call is first sent back to the model once, so it can answer another way. See [Blocks and refusals](https://docs.xenovia.io/observability/sessions.md#what-a-block-looks-like-to-your-app).
* A guardrail `escalate` lets the request proceed.
* Every answer carries `X-Xenovia-Decision` (`allowed`, `blocked` or `unchecked`). A blocked or unchecked one also carries `X-Xenovia-Reason`, a short code such as `policy:<rule>`; the refusal itself never names the policy or guardrail.
* There is no fail mode setting. When Neon can't be reached, a stage with anything enforced on it fails closed with `503` and `Retry-After: 5`. A stage with nothing enforced goes on unchecked (`X-Xenovia-Decision: unchecked`), and Monitor guardrails record the error and never block.

### 6. Failover

When the agent has [fallback providers](https://docs.xenovia.io/providers/fallbacks.md), the attempts run here, after enforcement. Each fallback is checked against the agent's request-stage policies again before it's called. Requests on the Anthropic-compatible routes never run a fallback route: they use the primary only.

## Supported providers

Xenovia speaks OpenAI format and Anthropic's Messages API to your app and translates each request for the provider upstream, so your app can use an OpenAI- or Anthropic-compatible client whatever provider is behind the agent. More than forty providers are supported: model developers (OpenAI, Anthropic, Google, Mistral, xAI and others), cloud platforms (Azure OpenAI, Microsoft Foundry, Amazon Bedrock, Google Vertex AI, Databricks), inference providers, routers, self-hosted servers and any OpenAI- or Anthropic-compatible endpoint. See [Supported providers](https://docs.xenovia.io/providers/overview.md) for the full list and the credentials each takes.

The provider your policy sees in `input.provider` is the provider's type as configured (`openai`, `microsoft-foundry`, `together`, ...), whatever API the runtime uses to reach it. A provider configured with a custom base URL keeps its type.

## Supported endpoints

| Endpoint | Use case |
| - | - |
| `POST /{agent_id}/v1/chat/completions` | Chat, agents, tool calling |
| `POST /{agent_id}/v1/responses` | OpenAI Agents SDK (Responses API) |
| `POST /{agent_id}/v1/messages` | Anthropic SDKs, the Claude Agent SDK and Claude Code (see [Anthropic SDK](https://docs.xenovia.io/agents/connect-your-app.md)) |
| `POST /{agent_id}/v1/messages/count_tokens` | Token counting for Anthropic clients |

The OpenAI base URL is `https://runtime.xenovia.io/{agent_id}/v1`; the Anthropic base URL is `https://runtime.xenovia.io/{agent_id}`. The `model` in a request is ignored: the provider's configured model is used.

Embeddings, legacy completions, model listing, and audio, image, video, batch, and container endpoints are not routed and return `404`. Besides these inference routes, the runtime serves only the health endpoints, the decision endpoint `POST /v1/execute`, and the coding-agent hook endpoints. Text, image, and file **inputs** are accepted; requests for audio output are rejected with `400`.

## Security

* **Credential isolation.** Provider credentials live in the agent's configuration and are resolved server-side; your app never holds them. Secrets are fetched over an internal channel and kept in memory, never written to Redis or into telemetry.
* **SSRF protection.** Provider base URLs are validated, and every connection to a provider is checked again against the address it resolves to. Link-local and cloud-metadata addresses are always rejected. Loopback and private addresses are rejected unless the runtime sets `XENOVIA_ALLOW_PRIVATE_PROVIDER_ENDPOINTS` (see [Hybrid](https://docs.xenovia.io/organization/hybrid.md)).
* **Config integrity.** Config snapshots and identity blobs are HMAC-signed. A revoked agent key stops working within about five minutes in the cloud.
* **Deployment.** In the standard cloud deployment Xenovia operates the runtime. A hybrid data-plane option runs the runtime inside your own cluster; ask your Xenovia contact for the deployment guide.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.