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

# Run Mixpeek locally in one container

> Build one Docker image and start it with one docker run. The API, Studio, Ray engine, MVS, MongoDB and Redis run on your machine with no cluster.

One Docker image runs the whole Mixpeek platform on your machine: the API, Studio, the Ray engine, MVS, MongoDB, Redis and an S3-compatible object store. Docker is the only prerequisite to run it.

<Warning>
  Mixpeek does not publish this image to a public registry. It bundles MongoDB Community Server (SSPL-1.0) and MinIO (AGPL-3.0). You build it from the Mixpeek repository, which needs repository access.
</Warning>

## Requirements

| Item          | Requirement                                                                                                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Docker        | Docker Desktop or Docker Engine, with `buildx`                                                                                                                                         |
| Docker memory | 16 GB                                                                                                                                                                                  |
| Free disk     | 28 GB. The checkout is about 2.5 GB. A first build leaves a 12.3 GB build cache next to an image of about 5 GB, and a 100-document run leaves up to 3.9 GB of Ray spill on the volume. |
| Build tools   | `git` and `rsync`. The build needs them. Running the image does not.                                                                                                                   |
| Architecture  | `linux/arm64` or `linux/amd64`, built for the machine you build on                                                                                                                     |
| Network       | The build needs it. The running container works with the network off in its default mode.                                                                                              |

## Set it up

<Steps>
  <Step title="Build the image">
    Check out `server/` and `studio/` from the repository, with your usual GitHub credentials for the private repository. Stage Studio into the build context, then build.

    ```bash theme={null}
    git clone --depth 1 --no-checkout https://github.com/mixpeek/mixpeek.git
    cd mixpeek
    git sparse-checkout set server studio
    git checkout
    bash server/scripts/stage-studio-src.sh
    docker buildx build -f server/Dockerfile.standalone \
      -t mixpeek/standalone:dev --load server
    ```

    The build targets your machine's architecture. Add `--platform linux/arm64` or `--platform linux/amd64` to choose one.

    The checkout took about 3 minutes and 2.5 GB. A full clone with history took 4 minutes and 6.3 GB. A cold build on an 8-CPU arm64 Linux VM with no cached images took between 7 and 13 minutes across two runs. Later builds reuse cached layers.
  </Step>

  <Step title="Start the container">
    Set Docker's memory to 16 GB first. In Docker Desktop, open Settings, then Resources.

    ```bash theme={null}
    docker run -d --name mixpeek --stop-timeout 60 \
      -p 8000:8000 -p 3000:3000 -p 8099:8099 \
      -v mixpeek-data:/data \
      mixpeek/standalone:dev
    ```

    | Port   | Serves                     |
    | ------ | -------------------------- |
    | `8000` | The API                    |
    | `3000` | Studio                     |
    | `8099` | Health for every component |

    The volume `mixpeek-data` holds all state. Publish only these three ports. If another service on your machine already uses one of them, change the number on the left of that `-p` pair, for example `-p 13000:3000`.

    With Colima, start the VM with `colima start --memory 16`. If a container named `mixpeek` already exists, remove it first with `docker rm -f mixpeek`. The volume stays.

    `--stop-timeout 60` gives the stack time to shut down. MVS needs about 10.6 seconds to stop cleanly. Docker waits 10 seconds by default, then kills the container. With the flag, `docker stop` takes about 23 seconds and exits 0.
  </Step>

  <Step title="Wait until it is healthy">
    ```bash theme={null}
    until curl -s localhost:8099/health | grep -q '"status": "healthy"'; do sleep 5; done
    ```

    The endpoint reports `starting` while Ray builds its Serve applications. In a clean-host run, `/ready` answered after 44 seconds and the seed step finished after 48 seconds. A restart with data on the volume takes about a minute. Allow up to 10 minutes on a cold start.

    If the status becomes `degraded`, run `docker logs mixpeek` and look for the component named in `/health`.
  </Step>

  <Step title="Read your credentials">
    The container creates one organization on first start and writes its API key to the volume.

    ```bash theme={null}
    docker exec mixpeek /app/standalone/entrypoint.sh credentials
    ```

    The command prints two comment lines that start with `#` and five settings: `MIXPEEK_API_KEY`, `MIXPEEK_NAMESPACE_ID`, `MIXPEEK_ORG_NAME`, `MIXPEEK_ORG_ID` and `MIXPEEK_API_URL`. The key survives restarts.

    Export the settings into your shell:

    ```bash theme={null}
    eval "$(docker exec mixpeek /app/standalone/entrypoint.sh credentials | grep -v '^#' | sed 's/^/export /')"
    ```
  </Step>

  <Step title="Call the API">
    List the buckets in your namespace. The response includes the starter bucket the container seeds.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -s -X POST http://localhost:8000/v1/buckets/list \
        -H "Authorization: Bearer $MIXPEEK_API_KEY" \
        -H "X-Namespace: $MIXPEEK_NAMESPACE_ID" \
        -H "Content-Type: application/json" \
        -d '{}'
      ```

      ```python Python theme={null}
      import os
      import requests

      resp = requests.post(
          "http://localhost:8000/v1/buckets/list",
          headers={
              "Authorization": f"Bearer {os.environ['MIXPEEK_API_KEY']}",
              "X-Namespace": os.environ["MIXPEEK_NAMESPACE_ID"],
          },
          json={},
      )
      for bucket in resp.json()["results"]:
          print(bucket["bucket_name"], bucket["bucket_id"])
      ```

      ```javascript JavaScript theme={null}
      const resp = await fetch("http://localhost:8000/v1/buckets/list", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.MIXPEEK_API_KEY}`,
          "X-Namespace": process.env.MIXPEEK_NAMESPACE_ID,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({}),
      });
      const { results } = await resp.json();
      for (const bucket of results) console.log(bucket.bucket_name, bucket.bucket_id);
      ```
    </CodeGroup>

    The Python SDK takes the local address too, and the address needs the `/v1` on the end: `Mixpeek(api_key=..., base_url="http://localhost:8000/v1")`. Without it every call returns 404. The `MIXPEEK_API_URL` that the credentials command prints has no `/v1`.
  </Step>

  <Step title="Add documents and search">
    The starter bucket `sample-documents` is empty. This script runs inside the container. It uploads four short documents, runs a batch through Ray, waits for it to finish, and searches with the starter retriever `search`. It takes about 30 seconds.

    ```bash theme={null}
    docker exec -i mixpeek bash -s <<'EOF'
    . /data/seed/credentials.env
    API=http://127.0.0.1:8000
    H=(-H "Authorization: Bearer $MIXPEEK_API_KEY" -H "X-Namespace: $MIXPEEK_NAMESPACE_ID" -H "Content-Type: application/json")
    id() { jq -r --arg n "$2" ".results[] | select(.$1_name==\$n) | .$1_id"; }
    BUCKET=$(curl -s -X POST $API/v1/buckets/list "${H[@]}" -d '{}' | id bucket sample-documents)
    COLLECTION=$(curl -s -X POST $API/v1/collections/list "${H[@]}" -d '{}' | id collection documents)
    RETRIEVER=$(curl -s -X POST $API/v1/retrievers/list "${H[@]}" -d '{}' | id retriever search)

    OBJECTS=()
    for text in \
      "To reset your password, open Settings, choose Security and select Reset password." \
      "Invoices are issued on the first of each month with payment terms of net 30." \
      "A retriever is a saved multi-stage search pipeline: filter, search, rerank and format." \
      "API keys can be rotated at any time and the old key stops working at once."; do
      OBJECTS+=("$(curl -s -X POST $API/v1/buckets/$BUCKET/objects "${H[@]}" \
        -d "$(jq -n --arg t "$text" '{blobs: [{property: "content", type: "text", data: $t}]}')" | jq -r .object_id)")
    done

    BATCH=$(curl -s -X POST $API/v1/buckets/$BUCKET/batches "${H[@]}" \
      -d "$(jq -n --arg c "$COLLECTION" --argjson o "$(printf '%s\n' "${OBJECTS[@]}" | jq -R . | jq -s .)" '{object_ids: $o, collection_ids: [$c]}')" | jq -r .batch_id)
    TASK=$(curl -s -X POST $API/v1/buckets/$BUCKET/batches/$BATCH/submit "${H[@]}" -d "$(jq -n --arg c "$COLLECTION" '{collection_ids: [$c]}')" | jq -r .task_id)
    until [ "$(curl -s $API/v1/tasks/$TASK "${H[@]}" | jq -r .status)" = COMPLETED ]; do sleep 3; done

    curl -s -X POST $API/v1/retrievers/$RETRIEVER/execute "${H[@]}" \
      -d '{"inputs": {"query": "how do I reset my password"}}' \
      | jq -r '.documents[] | "\(.score * 100 | round / 100)  \(.content)"'
    EOF
    ```

    The output lists the documents with their scores, best match first. The document about resetting a password comes first, with a score near 0.8. The other three score close to zero.
  </Step>

  <Step title="Open Studio">
    Open `http://localhost:3000`. Studio needs no sign-in. A banner across the top says authentication is bypassed. Studio calls the API in this container with the seeded key.

    The seeded namespace `default` holds a starter bucket, a starter collection and a retriever named `search`.
  </Step>
</Steps>

## Check that everything works

Two test suites ship inside the image. Both run against the container itself.

```bash theme={null}
docker exec mixpeek /app/standalone/entrypoint.sh e2e -n 100
docker exec mixpeek /app/standalone/entrypoint.sh matrix
```

| Suite    | What it does                                                                                                                                                             |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `e2e`    | Creates its own organization, uploads `-n` documents, runs a batch through Ray, queries a retriever, clusters the documents, and deletes everything it made.             |
| `matrix` | Runs create, list, get, update, delete and execute against every primitive the API exposes. It deletes what it made in reverse order and checks each delete returns 404. |

The `e2e` run prints `(manifest contract validator not found, skipping)`. That is expected. The matrix prints one row per primitive and operation, 147 in all: 145 `PASS` and 2 `VOID`. The two `VOID` rows call an LLM and need a key. A row is `PASS`, `FAIL`, or `VOID` when the container cannot exercise it. The command exits with status 1 on any `FAIL`. The report is at `/data/logs/lifecycle-matrix/lifecycle-matrix.md` inside the container.

## Choose the default extractor

The seeded namespace uses `text_extractor`. It runs the MiniLM model (`all-MiniLM-L6-v2`, 384 dimensions), and the image carries the weights. This default needs no API key and makes no paid call. It works with the network off.

To use the multimodal `universal_extractor` instead, pass a Gemini or OpenAI key and name the extractor. The container applies the default when it creates the organization, so start from an empty volume with `docker rm -f mixpeek && docker volume rm mixpeek-data`.

```bash theme={null}
docker run -d --name mixpeek --stop-timeout 60 \
  -p 8000:8000 -p 3000:3000 -p 8099:8099 \
  -v mixpeek-data:/data \
  -e GEMINI_API_KEY=... \
  -e GEMINI_PROJECT_ID=... \
  -e MIXPEEK_DEFAULT_NAMESPACE_EXTRACTOR=universal_extractor \
  mixpeek/standalone:dev
```

Calls to Gemini or OpenAI bill your provider account for each object processed. `/health` reports `"mode": "keyed"` when a key is present.

## Media extractors

The image serves two inference apps: MiniLM and `taxonomy_join`. It carries no GPU models. The image, audio and video extractors resolve to models such as SigLIP, CLAP or ArcFace, and the image does not include them.

The image accepts media files, detects their type, stores them and lists them. Only the embedding step cannot run. The media test driver reports that step as `VOID` and names the missing model:

```bash theme={null}
docker exec mixpeek python3 /app/standalone/media_lifecycle_e2e.py
```

In keyed mode, `universal_extractor` embeds media through the Gemini API.

## Add an extractor with YAML

Put a `*.yaml` file in a directory, mount it at `/data/plugins`, and restart the container. The extractor appears in the API next to the built-in ones. You write no Python and rebuild nothing.

```yaml theme={null}
name: product_copy_embedder
version: v1
description: Embeds product marketing copy with MiniLM.
extends: text_extractor/v1
input:
  field: content
output:
  vector_index:
    model: all_minilm_l6_v2_v1
```

Remove the running container first. The volume stays, so your data does.

```bash theme={null}
docker rm -f mixpeek
docker run -d --name mixpeek --stop-timeout 60 \
  -p 8000:8000 -p 3000:3000 -p 8099:8099 \
  -v mixpeek-data:/data \
  -v "$PWD/my-plugins":/data/plugins \
  mixpeek/standalone:dev
```

The Docker daemon has to see the directory you mount. With Colima or Lima, use a path under your home directory.

The extractor is listed once the container is healthy, and a namespace has to enable it before a collection can use it. Enable it with a `PATCH`. It adds the extractor to the ones the namespace already has.

```bash theme={null}
curl -s -X PATCH http://localhost:8000/v1/namespaces/$MIXPEEK_NAMESPACE_ID \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $MIXPEEK_NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"feature_extractors": [{"feature_extractor_name": "product_copy_embedder", "version": "v1"}]}'
```

Then create a collection whose `feature_extractor` is `{"feature_extractor_name": "product_copy_embedder", "version": "v1", "input_mappings": {"text": "content"}}`, the same way you would for `text_extractor`. A batch through it completed in 21 seconds and produced 384-dimension MiniLM vectors.

`extends` reuses a built-in extractor's definition and Ray pipeline. The model registry sets the vector dimensions, so the YAML does not state them. A spec that fails to load stops the container.

## Operate the container

| Task                   | Command                                                                             |
| ---------------------- | ----------------------------------------------------------------------------------- |
| Component health       | `curl -s localhost:8099/health`                                                     |
| Can it serve a request | `curl -s localhost:8099/ready`                                                      |
| Process table          | `docker exec mixpeek /app/standalone/entrypoint.sh status`                          |
| Task runtime           | `docker exec mixpeek /app/standalone/entrypoint.sh work`                            |
| Logs                   | `docker logs mixpeek`                                                               |
| Stop and start         | `docker stop mixpeek` then `docker start mixpeek`. The stop takes about 23 seconds. |
| Start over             | `docker rm -f mixpeek && docker volume rm mixpeek-data`                             |

The volume survives `docker stop`, `docker start` and replacing the container. If you delete the volume, the container creates a new organization and a new API key on the next start.

The image runs no Celery process and no broker. A Mongo-backed work ledger and a Ray dispatcher run the background tasks. `celery-worker` and `celery-beat` show as `disabled` in `/health`.

## Memory

Give Docker 16 GB. The idle container uses about 7.8 GiB, and 7.4 GiB of that is Ray.

| Docker memory | Measured result                                              |
| ------------- | ------------------------------------------------------------ |
| 6 GB          | The platform boots. Ray's memory monitor then kills workers. |
| 12 GB         | The platform boots. A 100-document batch does not finish.    |
| 16 GB         | The `e2e` and `matrix` suites complete.                      |

## What the image leaves out

| Left out   | What you see                                                                                                                              |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| ClickHouse | Analytics is off. The `/v1/analytics` endpoints answer empty. Events on your resources still land in the namespace `_signals` collection. |
| GPU models | E5-large, SigLIP, CLAP, DINOv2, the BGE reranker and ArcFace are absent.                                                                  |

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/docs/overview/quickstart">
    Create a namespace, add data and search.
  </Card>

  <Card title="Concepts" icon="book" href="/docs/overview/concepts">
    Namespaces, buckets, collections and retrievers.
  </Card>

  <Card title="Studio" icon="layer-group" href="/docs/studio/quickstart">
    Work with the same platform in the UI.
  </Card>

  <Card title="Deployment" icon="server" href="/docs/operations/deployment">
    Kubernetes and managed Ray topologies.
  </Card>
</CardGroup>