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

# Deployment Models

> Three ways to run Mixpeek, and exactly what each party owns in every one

Mixpeek runs in three shapes. They differ in one dimension: how much of the stack
you own. The API, the SDKs and the primitives are identical across all three, and
code written against one runs unchanged against the others.

This page names who owns what, so a security review can answer its questions
without a call.

## The ownership ladder

|                              | Cloud account | Kubernetes | Nodes & storage      | Mixpeek software plane            | Who operates                                             | You pay for                |
| ---------------------------- | ------------- | ---------- | -------------------- | --------------------------------- | -------------------------------------------------------- | -------------------------- |
| **Mixpeek Cloud**            | Mixpeek       | Mixpeek    | Mixpeek              | Mixpeek                           | Mixpeek                                                  | Usage                      |
| **Mixpeek Cloud, dedicated** | Mixpeek       | Mixpeek    | Mixpeek, yours alone | Mixpeek                           | Mixpeek                                                  | Usage + dedicated capacity |
| **Customer-hosted**          | **You**       | **You**    | **You**              | Mixpeek, in a namespace you grant | You operate the substrate, Mixpeek operates its software | Your cloud bill + licence  |

There are two products behind those three rows. The third row is the one with a boundary worth
drawing, and it sits in exactly one place:

**You provide the substrate. Mixpeek provides and operates the software.**

| You own                     | Mixpeek owns                |
| --------------------------- | --------------------------- |
| Cloud account or datacenter | MVS                         |
| Kubernetes                  | Ray                         |
| CPU and GPU nodes           | Execution logic             |
| Disks and storage classes   | Python and CUDA environment |
| Object storage              | Models                      |
| Networking                  | Serve, indexing, retrieval  |
| IAM                         | The software lifecycle      |
| Quotas and policies         |                             |

**Both planes move together.** In customer-hosted Mixpeek the data plane and the
compute plane are in your environment: MVS shards on your disks, Ray on your
nodes, your object storage. That is the whole point, and it is why we do not offer
a shape that moves only one of them.

<Note>
  The test this architecture is built around: **can Mixpeek upgrade itself without
  asking your platform team to upgrade a dependency first?** Because we ship our own
  Ray, Python, CUDA and MVS as containers, mostly yes. Your Kubernetes version,
  storage capabilities and GPU drivers remain a compatibility boundary, but that is
  a much smaller and slower-moving interface than one where our release cadence
  depends on your runtime.
</Note>

### The vector store, in every row

Every row above stores vectors in **Mixpeek Vector Store on object storage**.
That is what we run, in all four models. Your vectors live in object storage in
the row's data plane, not in a separate database you have to operate.

In customer-hosted Mixpeek, MVS runs **in your Kubernetes, on your disks**. It is
Mixpeek software, operated by Mixpeek, running on substrate you provide. Your
vectors do not leave your environment.

MVS is a separate service rather than a Ray workload, deliberately: owning the
storage layer end to end is what makes the learned index possible. That is why it
moves with the rest of the plane rather than being something you host separately.

Mixpeek Vector Store is the vector store in all three shapes. Bringing your own
vector database is not a deployment we offer, because owning the storage layer end
to end is what makes the learned index possible.

## What changes, and what does not

On both Mixpeek Cloud rows the control plane stays with Mixpeek: the API gateway,
auth, billing, and the routing that sends your requests to the right data plane.
What moves is where the work runs and whose hardware it runs on.

Customer-hosted is the row where that is a choice. The managed shape keeps the
control plane with Mixpeek and your namespace egresses to it; a fully self-hosted
install keeps it in your namespace and needs no outbound to us. The
[boundary section of the data-flow page](/docs/customer-hosted/data-flow#the-boundary-first)
gives the six collections involved and what the self-hosted shape gives up.

<Note>
  Your integration does not change between models. The same buckets, collections,
  extractors, retrievers, taxonomies and clusters, the same API keys, the same
  SDKs. Moving down the ladder changes your infrastructure obligations, not your
  code.
</Note>

## BYO Ray, in more detail

BYO Ray is the row where the most is yours, so it is the row with the most to
say. You already run Ray or KubeRay. Mixpeek runs its indexing and inference
workloads on it rather than asking you to stand up a second one.

<Note>
  This section is a summary. [Bring Your Own Ray](/docs/customer-hosted/overview) has the full
  contract: [every permission we ask for](/docs/customer-hosted/security-rbac), [what the
  qualification suite checks](/docs/customer-hosted/qualification), and [what each failure
  means](/docs/customer-hosted/troubleshooting).
</Note>

**What you grant.** One Kubernetes namespace, and two namespace-scoped Roles
inside it. Nothing of ours is cluster-scoped: no `ClusterRole`, no CRDs of ours,
no ability to create namespaces.

**The one exception, stated rather than buried.** KubeRay is cluster-scoped: it
ships 3 CustomResourceDefinitions and 5 ClusterRoles, and there is no
namespace-only way to install it. Most customers already run it, and where they
do not, their platform team installs it once with a Helm command we publish. If
you would rather we owned that too, the grant is
`customresourcedefinitions` + `clusterroles` + `clusterrolebindings`, and the
[qualification suite](/docs/customer-hosted/qualification) reports which side of that line you
are on. Both are supported; the difference is whether a Mixpeek release needing a
newer KubeRay waits on your change window.

**What stays yours.** Your node pools, quotas, taints, autoscaler policy and
network policy. Mixpeek's workloads schedule under your rules; they do not
change them.

**What we deploy.** Our engine image into that namespace, and ephemeral batch
jobs into the same namespace. A Ray cluster runs one image, so where we bring
our own cluster your Ray, Python and CUDA versions are not inputs to whether it
works.

**We bring our own Ray.** Mixpeek deploys a `RayService` into your namespace with
our image, our Serve applications and our worker groups, and submits batch as
`RayJob`s into the same namespace. Your Ray, Python and CUDA versions are not
inputs to whether it works, because a Ray cluster runs one image and that image is
ours.

<Note>
  **If you already run Ray**, we still bring our own rather than joining yours. That
  is deliberate. Running Mixpeek inside your Ray runtime would make your Ray, Python
  and CUDA versions a dependency of our release cadence, and would mean qualifying a
  new build per customer environment.

  Running Mixpeek on an existing customer `RayCluster` is possible and we have
  measured what it involves, but it is a compatibility exception rather than the
  supported shape. Ask if you need it.
</Note>

### Serve isolation on a shared cluster

If you run Mode 2, Mixpeek's Serve applications sit beside yours on a cluster
you own. How we deploy them depends on how *yours* were deployed, and the
difference is worth understanding before you grant access.

Ray Serve's configuration API is declarative over the whole application set: a
config that does not name an application removes it. Whether that reaches your
applications depends on whether Ray Serve holds a config for them.

| How your app was deployed                    | Does Serve hold its config | A whole-config deploy |
| -------------------------------------------- | -------------------------- | --------------------- |
| `serve.run(...)` in Python (imperative)      | No                         | **Leaves it alone**   |
| A config PUT / `serveConfigV2` (declarative) | Yes                        | **Removes it**        |

You can tell which you have: an application with an empty `deployed_app_config`
in `GET /api/serve/applications/` was deployed imperatively, and sits outside the
lifecycle that config governs.

Mixpeek does not use the whole-config path on a cluster it does not own. We add,
scale and remove **one named application at a time**, which cannot reach another
application regardless of how yours were deployed. For customers whose Serve
apps are declaratively deployed, that is protection against a real and measured
hazard rather than a precaution.

<Note>
  Measured on Ray 2.53.0 with KubeRay 1.5.1, on a single-head cluster with one
  application of each kind. It is enough to state the asymmetry above. It is not a
  promise that a whole-config deploy is safe on your cluster, and we do not make
  one.
</Note>

### Qualifying your cluster

Before anything is deployed, Mixpeek runs a qualification suite against your Ray
cluster and hands you the report. It checks reachability, the namespace-scoped
permissions, connectivity to your object storage and control-plane endpoints,
whether your node pools, taints and quotas remain authoritative when we schedule,
and whether our workloads leave your existing Ray applications, jobs and actors
untouched.

The report is a plain-text table of rows and verdicts. Rows that could not be
run say so rather than passing quietly, and a row that cannot establish something
reports what it could not determine rather than reporting an absence.

## Choosing a model

* **Mixpeek Cloud** if you want none of this. Most customers.
* **Mixpeek Cloud, dedicated** if you need isolated capacity but not custody.
* **Customer-hosted** if your data must stay in your environment, or your
  security posture requires that the software run on infrastructure you control.

Already running Ray or KubeRay is not by itself a reason to choose customer-hosted.
The reason is custody of the data and the substrate.

<Note>
  Moving between models is a deployment change, not a migration. Your namespaces,
  collections and retrievers are defined through the API and move with you.
</Note>