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

# Hybrid

> Run the Xenovia runtime in your own cluster, with provider keys that never leave it.

Run the Xenovia runtime inside your own cluster. Your agents' requests are served there and their provider credentials stay there, while you manage agents and policies from the same console.

For example, a hybrid agent's provider uses a credential reference instead of a key. Your cluster resolves it at request time, so the key never reaches Xenovia's servers.

Hybrid is set up with your Xenovia contact, who has the deployment guide. When your organization has it, admins see **Deployments** in **Settings**.

## How a hybrid agent works

A hybrid agent is served by the runtime in your own cluster. Its provider uses a credential reference that your cluster resolves at request time, and its endpoint is your deployment's ingress URL followed by `/{agent_id}/v1`.

## Register a deployment

**1. Create it**

In **Settings › Deployments**, choose **New deployment**. Give it a **Name**. **Ingress URL** is needed before developers connect, and **Data plane URL** (HTTPS, with a trusted certificate) is needed for viewing traces; both can be added later. Choose **Create deployment**.

**2. Copy the bootstrap token**

The token is shown once and can be redeemed once, before it expires. Store it in your cluster as the `SYNC_PLANE_BOOTSTRAP_TOKEN` secret.

**3. Deploy the sync plane**

Deploy the sync plane from `deploy/k8s` in the install pack. The deployment shows **Connected** once it checks in, in about 30 seconds.

Each deployment shows its **Status** (**Awaiting connection**, **Active** or **Revoked**) and **Connection**: **Connected**, or **Disconnected since** a time when no heartbeat arrived for 120 seconds. A connected deployment shows that it is reporting; it doesn't prove the runtime is healthy.

**Rotate credential** invalidates the current credential at once and gives a new bootstrap token; the sync plane goes dark until it has the new one. **Revoke** invalidates the credential for good.

## Runtime settings

> [accordion] Settings for Neon and model routing
>
> These runtime settings govern guardrails and model routing in a hybrid deployment:
>
> | Variable | Default | Meaning |
> | - | - | - |
> | `NEON_URL` | unset | Base URL of [Neon](https://docs.xenovia.io/control/neon.md). Required for guardrails and the purpose gate. Must be `https`, or `http` to a private host or one listed in `XENOVIA_NEON_ALLOW_HTTP_HOSTS` |
> | `NEON_API_KEY` | unset | The key the runtime sends to Neon |
> | `XENOVIA_NEON_ALLOW_HTTP_HOSTS` | unset | Comma-separated hosts Neon may be reached at over plain `http` |
> | `XENOVIA_GUARDRAIL_CONCURRENCY` | `64` | Neon calls allowed at once per runtime process; further calls wait a few seconds for a slot, then count as Neon being unreachable |
> | `XENOVIA_ALLOW_PRIVATE_PROVIDER_ENDPOINTS` | `false` | `true` lets provider base URLs target loopback, private, CGNAT, and cluster-local addresses. For hybrid and local development only; link-local and cloud-metadata addresses stay blocked |

> [!WARNING]
>
> Without a usable `NEON_URL`, Neon can't be reached: every stage with anything enforced on it fails closed with `503`, and every other stage goes on unchecked. Policies still run.

## Limitations

* A hybrid runtime can't load fallback credentials yet, so it skips every [fallback](https://docs.xenovia.io/providers/fallbacks.md) and serves from the primary.
* A provider that uses a credential reference is saved without the connection test, because its key stays in your cluster.
* Agents on a hybrid runtime can't be [simulated](https://docs.xenovia.io/simulation.md).
* Keys scoped to an inline sub-agent work only against the Xenovia cloud runtime, and a hybrid agent can't be linked as a sub-agent. See [Sub-agents](https://docs.xenovia.io/agents/sub-agents.md).

## What next?

> [card] [Runtime](https://docs.xenovia.io/reference/runtime.md)
>
> What the runtime does with each request.

> [card] [Providers](https://docs.xenovia.io/providers/overview.md)
>
> Add a provider for a hybrid agent.

> [card] [Neon](https://docs.xenovia.io/control/neon.md)
>
> What happens when Neon can't be reached.


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