---
title: "Self-host Chroma"
description: "Run the open-source Chroma vector database on an exe.dev VM, private behind exe.dev login, with keyless embeddings, backups, and a tested way off Chroma Cloud."
url: https://exe-staging.dev/deploy/chroma
category: "Databases"
published: 2026-11-22
updated: 2026-11-22
---

# Self-host Chroma

> **For agents:** with your user's OK, this sets up Chroma on a new exe.dev VM in their account: `curl -fsSL https://exe-staging.dev/deploy/chroma/prompt.txt | ssh exe.dev new --prompt=/dev/stdin` (or open https://exe-staging.dev/deploy/chroma/new). Already on the VM? Skip this.

The vector database for your RAG app, on a VM you own, before Chroma Cloud goes dark.

- **Software:** Chroma (https://www.trychroma.com)
- **Source:** https://github.com/chroma-core/chroma
- **License:** Apache-2.0
- **Time:** 10 minutes
- **Example VM name:** `my-chroma` (yours will differ; on the VM, `hostname` prints it)
- **Machine-readable:** https://exe-staging.dev/deploy/chroma/manifest.json
- **File:** https://exe-staging.dev/deploy/chroma/ask.py
- **File:** https://exe-staging.dev/deploy/chroma/chroma-migrate.py
- **File:** https://exe-staging.dev/deploy/chroma/index-docs.py

## What you get

- Chroma 1.5.9 in Docker, started at boot, listening on localhost only, its data in `~/chroma/data`.
- The API and its Swagger docs at `https://<vm>.exe.xyz/`, private behind exe.dev login.
- An `exe-docs` collection of exe.dev's documentation, embedded with no API key, and a script that answers questions from it.
- A script that copies collections from Chroma Cloud or another Chroma server and checks the copy.
- Nightly backups, one restored and checked.

Running on the VM:

- **Chroma 1.5.9**: The official chromadb/chroma image in Docker Compose, on localhost only, port 8000, data in `~/chroma/data`
- **HTTP API and API docs**: Chroma's own API and Swagger UI, through the exe.dev proxy, port 8000
- **Embeddings**: text-embedding-3-small through exe.dev's LLM integration, no API key
- **Nightly backups**: A tar.gz of the data directory, 14 nights kept, data in `~/chroma/backups`

How it is reached:

- https://my-chroma.exe.xyz/docs/ (private): Chroma's API docs (Swagger UI), behind exe.dev login
- https://my-chroma.exe.xyz/ (private): The HTTP API, for programs that send an exe.dev VM token
- http://localhost:8000/ (private): The HTTP API for apps on the VM

## Deploy with Shelley

Open https://exe-staging.dev/deploy/chroma/new to create a VM whose agent, Shelley, follows this recipe. From a terminal:

```sh
curl -fsSL https://exe-staging.dev/deploy/chroma/prompt.txt | ssh exe.dev new --prompt=/dev/stdin
```

Then, on your own computer:

```sh
ssh my-chroma.exe.xyz 'cd chroma && uv run ask.py "How do I make my VM public?"'
ssh exe.dev ssh-key generate-api-key --vm=my-chroma --label=chroma --exp=90d
```

Or follow the steps below by hand.

Chroma is an open-source vector database: you give it documents, it stores
them with their embeddings, and it finds the ones closest in meaning to a
question. That's the retrieval half of most RAG apps and agent memories.
Here it runs as one Docker container on an exe.dev VM, with its data on the
VM's disk, its API behind your exe.dev login, embeddings from exe.dev's LLM
integration with no API key, and nightly backups you've seen restored.

Chroma Cloud, the hosted version, stops taking writes on December 7, 2026
and shuts down on December 22. If your data is there,
[Leaving Chroma Cloud](#leaving-chroma-cloud) moves it to the VM and checks
the copy.

[exe.dev](https://exe.dev/) gives you persistent Linux VMs with HTTPS,
sign-in and a coding agent built in; this page sets up Chroma on one. We
tested Chroma 1.5.9 on November 22, 2026.

## Ask the docs a question

Shelley loads a demo collection while setting up: every page of exe.dev's
documentation, split at its headings into 534 chunks and embedded with
OpenAI's `text-embedding-3-small`. Ask it something. On your computer:

```bash
ssh my-chroma.exe.xyz 'cd chroma && uv run ask.py "How do I make my VM public?"'
```

```text
0.377  Sharing > Make the web server public  https://exe.dev/docs/sharing
0.426  Sharing > Sharing  https://exe.dev/docs/sharing
0.451  Sharing controls > Sharing controls  https://exe.dev/docs/teams/sharing-controls
0.482  Sharing controls > Turning off public sharing  https://exe.dev/docs/teams/sharing-controls
0.493  Team VMs > Web access  https://exe.dev/docs/teams/vms

Use:

    share set-public <vm>

Note: a team's sharing controls may prevent making VMs public.
Page used: Sharing: Make the web server public
```

The numbers are cosine distances, smaller is closer. Chroma embedded the
question with the same model as the documents, because the collection
remembers its embedding function, and returned the five nearest chunks;
then gpt-5.4-mini wrote the answer from them. Both calls go through
[exe.dev's LLM integration](/docs/integrations-llm). The whole round trip
takes about four seconds.

Two short scripts did this, both in `~/chroma` on the VM:

- [index-docs.py](https://exe-staging.dev/deploy/chroma/index-docs.py) fetches
  the pages listed in `https://exe.dev/llms.txt`, splits them, and upserts
  them into the `exe-docs` collection, in about seven seconds. Run it again
  whenever the docs change.
- [ask.py](https://exe-staging.dev/deploy/chroma/ask.py) queries the collection
  and asks a model to answer from what it found.

They're templates for your own data: change what `index-docs.py` reads
and how it splits it, and keep the rest.

## Open the API docs

Chroma has no admin UI, but it serves interactive docs for its API. Open
`https://my-chroma.exe.xyz/docs/` and sign in to exe.dev. exe.dev's proxy
adds HTTPS and lets only you in; Chroma itself listens only on the VM's
localhost. Under **Collection**, try **List collections** with tenant
`default_tenant` and database `default_database` to see `exe-docs`.

For a quick look from the VM's shell instead:

```bash
curl -s localhost:8000/api/v2/tenants/default_tenant/databases/default_database/collections | jq '.[].name'
```

## Use it from your app

On the VM, apps reach Chroma at `http://localhost:8000` with the regular
clients. Install the Python client, `chromadb-client`, which is the small,
client-only package (`uv add chromadb-client` or
`pip install chromadb-client`):

```python
import chromadb
from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction

client = chromadb.HttpClient(host="http://localhost:8000")
embed = OpenAIEmbeddingFunction(
    model_name="text-embedding-3-small",
    api_base="https://llm.int.exe.xyz/v1",
    api_key_env_var="CHROMA_OPENAI_API_KEY",
)
notes = client.get_or_create_collection(
    "notes", embedding_function=embed, configuration={"hnsw": {"space": "cosine"}}
)
notes.upsert(ids=["n1", "n2"], documents=["Buy oat milk", "Renew the TLS cert on Friday"],
             metadatas=[{"tag": "home"}, {"tag": "work"}])
print(notes.query(query_texts=["certificate expiry"], n_results=1, where={"tag": "work"}))
```

Run it with `CHROMA_OPENAI_API_KEY=exe-gateway` in the environment: the
LLM integration ignores the key, but the OpenAI library insists on one.
The collection stores the model name and base URL, so later
`get_collection("notes")` calls embed the same way without being told.

In JavaScript, `npm install chromadb @chroma-core/openai`:

```js
import { ChromaClient } from 'chromadb'
import { OpenAIEmbeddingFunction } from '@chroma-core/openai'

const client = new ChromaClient({ host: 'localhost', port: 8000 })
const notes = await client.getOrCreateCollection({
  name: 'notes',
  embeddingFunction: new OpenAIEmbeddingFunction({
    modelName: 'text-embedding-3-small',
    apiBase: 'https://llm.int.exe.xyz/v1',
    apiKeyEnvVar: 'CHROMA_OPENAI_API_KEY',
  }),
})
await notes.upsert({
  ids: ['n1', 'n2'],
  documents: ['Buy oat milk', 'Renew the TLS cert on Friday'],
  metadatas: [{ tag: 'home' }, { tag: 'work' }],
})
console.log(await notes.query({ queryTexts: ['certificate expiry'], nResults: 1, where: { tag: 'work' } }))
```

Apps and libraries that take a Chroma URL, such as AnythingLLM
(`CHROMA_ENDPOINT`) or LangChain's and LlamaIndex's Chroma stores, work
the same way with `http://localhost:8000`.

## Connect from your computer

The API at `https://my-chroma.exe.xyz/` is private: a browser gets the
exe.dev login page, and a program without credentials gets `401`. Programs
get through with an exe.dev [VM token](/docs/https-tokens-for-vms) in an
`X-Exedev-Authorization` header; the proxy checks it and removes it before
Chroma sees the request. On your computer, make a token for this VM:

```bash
ssh exe.dev ssh-key generate-api-key --vm=my-chroma --label=chroma --exp=90d
```

Save it as `EXE_TOKEN` in your shell, then:

```bash
curl -sS https://my-chroma.exe.xyz/api/v2/heartbeat -H "X-Exedev-Authorization: Bearer $EXE_TOKEN"
```

Expect `{"nanosecond heartbeat":...}`. Both clients take extra headers. In
Python:

```python
import os, chromadb

client = chromadb.HttpClient(
    host="my-chroma.exe.xyz", port=443, ssl=True,
    headers={"X-Exedev-Authorization": "Bearer " + os.environ["EXE_TOKEN"]},
)
print(client.get_collection("exe-docs").count())
```

In JavaScript:

```js
import { ChromaClient } from 'chromadb'
import '@chroma-core/openai'  // lets getCollection rebuild the stored embedding function

const client = new ChromaClient({
  host: 'my-chroma.exe.xyz', port: 443, ssl: true,
  headers: { 'X-Exedev-Authorization': `Bearer ${process.env.EXE_TOKEN}` },
})
console.log(await (await client.getCollection({ name: 'exe-docs' })).count())
```

We ran both, chromadb-client 1.5.9 and chromadb 3.5.0 for Node.js, with
queries and upserts. The LLM integration answers only on exe.dev VMs, so a
collection that embeds through it can't embed text on your laptop: pass
`query_embeddings` you made yourself, or your own embedding function.
(The JavaScript client warns that the OpenAI key isn't set when it
rebuilds the stored one; counting and fetching work regardless.) Add
`--ips=203.0.113.7/32` to the token command to accept it from one address
only.

## Connect from another VM

For an app on another exe.dev VM, the
[VM-to-VM integration](/docs/integrations-vm-to-vm) keeps the token off
that VM: exe.dev adds it at the edge. On your computer, with the app's VM
called `my-app`:

```bash
ssh exe.dev integrations add http-proxy --name chroma \
  --target https://my-chroma.exe.xyz/ --peer --attach vm:my-app
```

The app then uses `https://chroma.int.exe.xyz` (port 443, `ssl=True`) as
its Chroma host, with no headers.

Or put both VMs on your [Tailscale](https://tailscale.com/) network;
it's preinstalled. On both VMs:

```bash
sudo systemctl enable --now tailscaled
sudo tailscale up --hostname=$(hostname)
```

Open the login URL it prints (or join without one through exe.dev's
[Tailscale integration](/docs/integrations-tailscale-wif)). Then, on the
Chroma VM, forward port 8000 on its tailnet address to Chroma:

```bash
sudo tailscale serve --bg --tcp 8000 tcp://localhost:8000
```

The other VM reaches it as `http://my-chroma:8000`. Chroma has no password
of its own, so every device on your tailnet can read and change it; use
[Tailscale's access rules](https://tailscale.com/kb/1018/acls) to narrow
that down.

## Leaving Chroma Cloud

On October 23, 2026, Chroma
[announced](https://www.trychroma.com/cloud-wind-down) that Chroma Cloud
is winding down: from **December 7, 2026** it's read-only, and from
**December 22** you can't read your data either. Open-source Chroma
continues under Apache 2.0, and it's what this VM runs, so your app keeps
the same client library and API.

### What comes along, and what doesn't

Records move as they are: IDs, embeddings, documents, metadata and URIs,
with each collection's metadata, distance metric and embedding function
settings. Cloud stores vectors in a SPANN index and single-node Chroma in
HNSW; the copy is rebuilt as HNSW with the same metric, and `query()`
returns the same nearest neighbors.

Some things are Chroma Cloud services and don't exist in open-source
Chroma:

| On Chroma Cloud | On your VM |
|---|---|
| `collection.search()`, the Search API with `Knn` and `Rrf` | `collection.query()` with `where` and `where_document` filters |
| Sparse vectors and hybrid search (Splade, BM25 indexes) | Dense vectors only; Chroma refuses a sparse index ("not enabled in local") |
| Chroma Cloud Qwen and Splade embedding functions | Another embedding model, such as `text-embedding-3-small` through the LLM integration |
| Collection forking, Sync (GitHub and web crawling), the dashboard | Copy a collection with the script below; re-run your own loader |
| 300 results per query and 300 records per write | No such limits; the VM's memory is the limit |

If your collections use Chroma Cloud's Qwen embeddings, the stored vectors
still copy fine, but nothing can embed a new question the same way after
December 22. Re-embed those collections during the move with `--reembed`
(below), and change the embedding function in your app to match.

### Copy your collections

You need a Chroma Cloud API key (it starts with `ck-`; make one in the
Chroma Cloud dashboard) and the name of the database that
holds your collections. On the VM:

```bash
cd ~/chroma
read -rs CHROMA_API_KEY && export CHROMA_API_KEY   # paste the key, then Enter
export CHROMA_DATABASE=my-db                       # your Cloud database
python3 chroma-migrate.py --from-cloud --all
```

[chroma-migrate.py](https://exe-staging.dev/deploy/chroma/chroma-migrate.py) is
in `~/chroma` already, with only the Python standard library behind it. It
reads each collection 300 records at a time (Cloud's limit) with its
embeddings, upserts them into Chroma on the VM, and then checks: the
counts match, three random records have the same documents, metadata and
URIs on both sides, and each finds itself first when queried by its own
embedding. Upserts make it safe to run again after an interruption.

```text
Copying 2 collection(s) from https://api.trychroma.com (.../my-db) to http://localhost:8000 (default_database)
- faq: 8 records, space cosine, embeddings chroma-cloud-qwen
  ! faq: embedding function chroma-cloud-qwen is a Chroma Cloud service. The vectors copy fine,
    but nothing will embed new queries the same way after Cloud shuts down; consider --reembed.
  count: source 8, copy 8 ok
  records faq-3, faq-6, faq-1: documents, metadata and URIs match
  query by faq-3's embedding: ['faq-3', 'faq-1', 'faq-6'] ok
  ...
- products: 5000 records, space l2, embeddings as stored
  count: source 5000, copy 5000 ok
  ...
All collections copied and checked.
```

Other options: name collections instead of `--all`; `--to-database
cloud-copy` to keep them apart from your own; `--reembed
text-embedding-3-small` to embed every document again through the LLM
integration instead of copying the vectors (the collection then remembers
that model); `CHROMA_HOST=europe-west1.gcp.trychroma.com` (or similar) if
your Cloud database is in another region; `--from http://other-host:8000`
to copy from any other Chroma server.

> [!NOTE]
> We tested chroma-migrate.py against a Chroma 1.5.9 server standing in
> for Cloud, with 5,000 and 8-record collections, URIs, metadata and a
> Cloud-style Qwen embedding function, re-embedding included, and through
> the exe.dev proxy from another machine. We didn't have a Chroma Cloud
> account to copy from; the script uses the same v2 API and `x-chroma-token`
> header that Chroma's clients use with Cloud.

Chroma's own CLI has a copy command too, `chroma copy --from-cloud`. It
ships in the `chromadb` Python package and does the same job without the
checks (and without URIs):

```bash
uvx --from chromadb==1.5.9 chroma login --profile cloud --api-key ck-...
uvx --from chromadb==1.5.9 chroma copy --from-cloud --all --db my-db --host http://localhost:8000
```

### Point your app at the VM

In Python, swap `CloudClient` for `HttpClient`:

```python
# Before
client = chromadb.CloudClient(api_key="ck-...", tenant="...", database="my-db")

# After, on an exe.dev VM (or the integration from "Connect from another VM")
client = chromadb.HttpClient(host="http://localhost:8000")

# After, anywhere else
client = chromadb.HttpClient(host="my-chroma.exe.xyz", port=443, ssl=True,
                             headers={"X-Exedev-Authorization": "Bearer " + os.environ["EXE_TOKEN"]})
```

In JavaScript, swap `new CloudClient({...})` for
`new ChromaClient({ host, port, ssl, headers })` the same way. Then
replace any `collection.search(...)` calls with `collection.query(...)`,
and remove `CHROMA_API_KEY`, `CHROMA_TENANT` and `CHROMA_DATABASE` from
the app's environment. If you copied into a database other than
`default_database`, pass `database="cloud-copy"` to `HttpClient`.

## Qdrant or Weaviate instead

Moving anyway, you might pick another open-source vector database. The
same VM pattern works for both: a container on localhost, the exe.dev
proxy in front.

- **[Qdrant](https://qdrant.tech/)** (Apache 2.0, Rust, 35,000 GitHub
  stars, version 1.20 in November 2026) has an API key of its own,
  payload filtering, sparse vectors and hybrid search, quantization to
  save memory, and a web dashboard. It's one container:

  ```bash
  mkdir -p ~/qdrant && cd ~/qdrant
  (umask 077; echo "QDRANT__SERVICE__API_KEY=$(openssl rand -hex 24)" > qdrant.env)
  docker run -d --name qdrant --restart unless-stopped --env-file qdrant.env \
    -p 127.0.0.1:6333:6333 -v ~/qdrant/storage:/qdrant/storage qdrant/qdrant:v1.20.2
  ```

  The dashboard is at `https://my-chroma.exe.xyz:6333/dashboard`, behind
  exe.dev login and then the key in `qdrant.env`. Your data needs
  re-uploading through Qdrant's clients: its API is different from
  Chroma's, and nothing here converts collections.
- **[Weaviate](https://weaviate.io/)** (Go, 17,000 stars, version 1.40)
  builds in vectorizer and reranker modules, multi-tenancy and GraphQL.
  Its core is BSD-3-Clause; some enterprise features sit under a separate
  license and need a key. It's heavier to run than Chroma or Qdrant.

If your app only needs "store embeddings, find the nearest", staying on
Chroma is the least work: the client code barely changes.

## Keep your data

Every night, a small script stops Chroma for a few seconds, archives
`~/chroma/data` with the config to `~/chroma/backups/<UTC time>.tar.gz`,
and starts it again; the newest 14 stay. Writes during those seconds
fail, so retry them in your app, or move the timer to a quiet hour. A
backup on the same disk won't survive losing the VM, so keep a copy
elsewhere. On your computer:

```bash
rsync -av my-chroma.exe.xyz:chroma/backups/ chroma-backups/
```

exe.dev can also back up the whole VM disk to your own S3 bucket with
[VM backups](/docs/vm-backups), or send the files to a bucket on
[another VM](/deploy/s3-storage).

Something odd? On the VM, `cd ~/chroma && docker compose logs --tail 50`
usually explains it, or ask Shelley to look.

## The nuts and bolts

Happy clicking Deploy? You can stop here. These are the same setup steps
Shelley follows, plus the maintenance commands for later.

<details id="create-the-vm" data-manual-setup class="dp-details">
<summary>Install by hand</summary>

### Create a VM

On your computer (pick another name if `my-chroma` is taken):

```bash
ssh exe.dev new --name=my-chroma
ssh my-chroma.exe.xyz
```

Planning on millions of records? Make the disk bigger now, with
`--disk=100GB` on `new`, or later with
`ssh exe.dev resize my-chroma --disk=100GB`. All remaining commands run
**on the VM**, as `exedev`.

### Write the config

Docker is installed but not running; start it, and at every boot:

```bash
sudo systemctl enable --now docker.service
```

Chroma reads its settings from a YAML file. This one keeps the data in
`/data` inside the container and turns off `reset`, the API call that
wipes everything:

```bash
mkdir -p ~/chroma/data ~/chroma/backups
cat > ~/chroma/config.yaml <<'EOF'
# Chroma server settings: https://docs.trychroma.com/guides/deploy/docker
persist_path: /data
allow_reset: false
EOF
```

The Compose file pins the version, publishes the port on localhost only
(exe.dev's proxy reaches it there), and runs Chroma as your user, so the
files in `~/chroma/data` are yours:

```bash
cat > ~/chroma/compose.yaml <<EOF
name: chroma
services:
  chroma:
    image: chromadb/chroma:1.5.9
    restart: unless-stopped
    user: "$(id -u):$(id -g)"
    ports: ["127.0.0.1:8000:8000"]
    volumes:
      - ./data:/data
      - ./config.yaml:/config.yaml:ro
EOF
```

### Start Chroma

```bash
cd ~/chroma
docker compose up -d
timeout 60 sh -c 'until curl -sf localhost:8000/api/v2/heartbeat >/dev/null; do sleep 1; done'
curl -s localhost:8000/api/v2/heartbeat; echo
```

Expect `{"nanosecond heartbeat":...}` after about ten seconds. The image
is a 140 MB download.

### Load the demo collection

Fetch the three scripts and load exe.dev's docs:

```bash
cd ~/chroma
for f in index-docs.py ask.py chroma-migrate.py; do
  curl -fsSO https://exe-staging.dev/deploy/chroma/$f
done
uv run index-docs.py
uv run ask.py "How do I make my VM public?"
```

Expect `... pages, ... chunks; ... records in exe-docs`, then five sources
with Sharing first and an answer that mentions `share set-public`. The
scripts use the LLM integration, attached to every VM by default; a `403`
or connection error means it's off for this VM
([LLM integration](/docs/integrations-llm)).

### Set up nightly backups

```bash
cat > ~/chroma/backup.sh <<'EOS'
#!/usr/bin/env bash
# Stop Chroma for a moment, archive its data and config to
# ~/chroma/backups/<UTC time>.tar.gz, and start it again.
# Keeps the 14 newest backups.
set -euo pipefail
keep=14
cd "$HOME/chroma"
name=backups/$(date -u +%Y%m%d-%H%M%S).tar.gz
docker compose stop -t 30 chroma >/dev/null 2>&1
trap 'docker compose start chroma >/dev/null 2>&1' EXIT
tar -czf "$name.part" data config.yaml compose.yaml
mv "$name.part" "$name"
ls -1 backups/2*.tar.gz | head -n -"$keep" | xargs -r rm -f --
echo "$HOME/chroma/$name"
EOS
chmod +x ~/chroma/backup.sh
```

Schedule it for every night, then take a first backup:

```bash
sudo tee /etc/systemd/system/chroma-backup.service >/dev/null <<EOF
[Unit]
Description=Back up Chroma to ~/chroma/backups
After=docker.service

[Service]
Type=oneshot
User=$USER
ExecStart=$HOME/chroma/backup.sh
EOF
sudo tee /etc/systemd/system/chroma-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up Chroma every night

[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now chroma-backup.timer
sudo systemctl start chroma-backup.service
systemctl list-timers chroma-backup.timer
ls -l ~/chroma/backups
```

Expect a next run time and one `.tar.gz` file. For failures:
`journalctl -u chroma-backup.service`.

### Test a backup

Start a second Chroma on port 8001 from the newest backup, and compare its
`exe-docs` count with the live one:

```bash
latest=$(ls -1 ~/chroma/backups/2*.tar.gz | tail -n 1)
mkdir -p /tmp/chroma-restore && tar -xzf "$latest" -C /tmp/chroma-restore
docker run -d --name chroma-restore-test --user "$(id -u):$(id -g)" -p 127.0.0.1:8001:8000 \
  -v /tmp/chroma-restore/data:/data -v /tmp/chroma-restore/config.yaml:/config.yaml:ro \
  chromadb/chroma:1.5.9 >/dev/null
timeout 60 sh -c 'until curl -sf localhost:8001/api/v2/heartbeat >/dev/null; do sleep 1; done'
count() {
  local b=localhost:$1/api/v2/tenants/default_tenant/databases/default_database/collections
  curl -s "$b/$(curl -s "$b/exe-docs" | jq -r .id)/count"
}
echo "live $(count 8000), restored $(count 8001)"
docker rm -f chroma-restore-test >/dev/null && rm -rf /tmp/chroma-restore
```

Expect the same number twice, such as `live 534, restored 534`.
Installation done; continue with
[Ask the docs a question](#ask-the-docs-a-question).

</details>

<details id="back-up-and-restore" class="dp-details">
<summary>Back up and restore</summary>

On the VM, `~/chroma/backup.sh` takes an extra backup and prints its file.
A backup is the whole data directory: a SQLite database
(`chroma.sqlite3`) with the documents and metadata, and a directory of
HNSW index files per collection.

### Restore on this VM

This replaces everything with the backup. Take a fresh backup first, so
you can change your mind:

```bash
cd ~/chroma
./backup.sh
docker compose down
mv data data.old
tar -xzf backups/20261122-033012.tar.gz data
docker compose up -d
```

Check your collections, then `rm -rf ~/chroma/data.old`. To bring back a
single collection instead, start the backup on port 8001 as in
[Test a backup](#test-a-backup) and copy it across with
`python3 chroma-migrate.py --from http://localhost:8001 notes`.

### Restore on a new VM

Create the VM, start Docker, copy the backup over, unpack it into
`~/chroma` and start it. On your computer:

```bash
ssh exe.dev new --name=my-chroma-2
scp chroma-backups/20261122-033012.tar.gz my-chroma-2.exe.xyz:
ssh my-chroma-2.exe.xyz 'sudo systemctl enable --now docker.service && mkdir -p chroma/backups && tar -xzf 2026*.tar.gz -C chroma && cd chroma && docker compose up -d'
```

Then set up the backup timer from
[Set up nightly backups](#set-up-nightly-backups) on the new VM.

### The whole VM

[VM backups](/docs/vm-backups) copy the VM's entire disk to your own S3
bucket, incrementally. A snapshot of a running Chroma comes back like
after a power cut, which SQLite survives but the newest index writes may
not; the nightly archives are taken with Chroma stopped.

</details>

<details id="update" class="dp-details">
<summary>Update Chroma</summary>

Chroma's releases are on
[GitHub](https://github.com/chroma-core/chroma/releases); read the notes
for every version between yours and the new one, especially
[migration notes](https://docs.trychroma.com/docs/overview/migration).
Then, on the VM, back up, change the tag, and restart:

```bash
cd ~/chroma
./backup.sh
sed -i 's|chromadb/chroma:.*|chromadb/chroma:1.5.10|' compose.yaml
docker compose pull && docker compose up -d
timeout 60 sh -c 'until curl -sf localhost:8000/api/v2/heartbeat >/dev/null; do sleep 1; done'
docker compose images
```

Requests fail for the few seconds the new container takes to start. Keep
your clients on the same version as the server: `chromadb-client==1.5.10`
in Python. To go back, put the old tag back and restore the backup from
before the update: a newer Chroma may change the data format.

</details>

<details id="troubleshooting" class="dp-details">
<summary>Something not working?</summary>

On the VM, Chroma's log usually has the answer:

```bash
cd ~/chroma && docker compose ps && docker compose logs --tail 50
```

- **`401` from `my-chroma.exe.xyz`:** exe.dev wants a login or a token.
  Check the header name, `X-Exedev-Authorization: Bearer <token>`, and that
  the token was made with `--vm=my-chroma` and hasn't expired.
- **`Could not connect to a Chroma server` from Python:** through the
  proxy, the client needs `port=443, ssl=True` and the token header; a
  `401` looks like this too. On the VM, use `host="http://localhost:8000"`,
  and check `docker compose ps`.
- **`Could not build embedding function openai from config`, or `OpenAI
  API key is not set`:** set `CHROMA_OPENAI_API_KEY=exe-gateway` (any
  value does) in the app's environment.
- **`Sparse vector indexing is not enabled in local`:** sparse and hybrid
  search are Chroma Cloud only; drop the sparse index from the schema.
- **`Collection expecting embedding with dimension of 1536, got 384`:**
  the query was embedded with a different model than the collection.
  Use the collection's stored embedding function (call `get_collection`
  without one), or the same model by hand.
- **`Permission denied` in the logs after a restore:** the files belong to
  root. `sudo chown -R $(id -u):$(id -g) ~/chroma/data`.
- **Disk filling up:** `du -sh ~/chroma/data ~/chroma/backups`. Lower
  `keep` in `~/chroma/backup.sh`, delete collections you don't need, or
  grow the disk with `ssh exe.dev resize my-chroma --disk=100GB`.

</details>

## Frequently asked questions

### Chroma Cloud is shutting down. When do I have to move?

Before December 7, 2026, if your app writes to Chroma Cloud: that day Cloud turns read-only, and on December 22 reads stop too, according to [Chroma's wind-down notice](https://www.trychroma.com/cloud-wind-down). Open-source Chroma, the same database without the hosted service, stays Apache 2.0. [Leaving Chroma Cloud](#leaving-chroma-cloud) shows the move to a VM.

### How much does it cost to self-host Chroma on exe.dev?

Chroma is free and open source under Apache 2.0. You pay for your [exe.dev plan](https://exe.dev/pricing), and for a bigger disk if your collections outgrow the 25 GB a new VM starts with. Embeddings through the LLM integration count against your exe.dev [LLM allocation](/docs/integrations-llm); embedding all of exe.dev's docs, 450,000 characters, is one cheap batch.

### Does self-hosted Chroma have a password or API key?

No. Since 1.0 the open-source server has no authentication of its own, so this page keeps it on localhost and lets exe.dev's proxy decide who gets in: your exe.dev login in a browser, a [VM token](#connect-from-your-computer) in a program, or a [VM-to-VM integration](#connect-from-another-vm) for your other VMs. Don't make the VM public: anyone could read and delete everything.

### How big a VM does Chroma need?

Chroma keeps the vector index of the collections in use in memory: about 6 KB per record for 1,536-dimension embeddings, plus the graph. A new VM's 8 GB is plenty for a few hundred thousand records; copying 5,000 records took 3 seconds on our 2-CPU test VM. Resize with `ssh exe.dev resize my-chroma --memory=16GB` when you need more.

### Do I need an OpenAI API key for embeddings?

No. The scripts here use text-embedding-3-small through exe.dev's [LLM integration](/docs/integrations-llm), which needs no key on the VM. To embed on the VM's own CPU instead, Chroma's default all-MiniLM-L6-v2 model works offline: it embedded the 534 doc chunks in 20 seconds on 2 CPUs, with weaker results on long text.

### Can I run Chroma without Docker?

Yes: `uvx --from chromadb==1.5.9 chroma run --path ~/chroma/data --host 127.0.0.1 --port 8000` runs the same server from the Python package, and you'd write your own systemd unit for it. This page uses the official image because it pins the version in one file and Docker restarts it after a reboot.

### Chroma, pgvector, Qdrant or Weaviate?

If your app already has PostgreSQL, pgvector keeps the vectors next to the rows they belong to, as the [Mem0 page](/deploy/mem0) does. Chroma is the simplest dedicated store and has the gentlest Python and JavaScript clients. Qdrant and Weaviate add API keys, hybrid search and clustering; see [Qdrant or Weaviate instead](#qdrant-or-weaviate-instead).


## Related

- [Self-host PostgreSQL](https://exe-staging.dev/deploy/postgres.md): Your own Postgres on a real disk, with backups you've actually restored.
- [Self-host Mem0, one memory for agents on all your VMs](https://exe-staging.dev/deploy/mem0.md): One memory server for the agents on all your VMs. No OpenAI key.
- [Run Claude-Mem on a remote server](https://exe-staging.dev/deploy/claude-mem.md): Memory for Claude Code, Codex and T3 Code, on a VM that never sleeps.
- [Self-host Dify](https://exe-staging.dev/deploy/dify.md): Build and publish AI apps and workflows. Models without API keys.
- [Self-host ClickHouse](https://exe-staging.dev/deploy/clickhouse.md): Fast SQL analytics on events and logs, on a real disk, private by default.
- [Deploy a Docker Compose app from GitHub](https://exe-staging.dev/deploy/docker-compose.md): Your compose.yaml on a VM of its own. git push to deploy.
