Skip to content

Self-host Chroma

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

Deploy on exe.dev

Shelley handles the setup. About 10 minutes.

Prefer a terminal?
curl -fsSL https://exe-staging.dev/deploy/chroma/prompt.txt | ssh exe.dev new --prompt=/dev/stdin

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 moves it to the VM and checks the copy.

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.

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.
What's running, and where
Private https://my-chroma.exe.xyz/docs/ Chroma's API docs (Swagger UI), behind exe.dev login
Private https://my-chroma.exe.xyz/ The HTTP API, for programs that send an exe.dev VM token
Private http://localhost:8000/ The HTTP API for apps on the VM
my-chroma.exe.xyz exe.dev VM
Chroma 1.5.9 The official chromadb/chroma image in Docker Compose, on localhost only :8000~/chroma/data
HTTP API and API docs Chroma's own API and Swagger UI, through the exe.dev proxy :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 ~/chroma/backups

Deploy with Shelley#

Click Deploy and Shelley will set up Chroma on a new VM, then check that it works. No config-file wrangling required.

Prefer a terminal?
curl -fsSL \
  https://exe-staging.dev/deploy/chroma/prompt.txt \
  | ssh exe.dev new --prompt=/dev/stdin

When it's done, run this on your computer (only you can):

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
What Shelley is told
Set up Chroma on this VM by following the exe.dev recipe at https://exe-staging.dev/deploy/chroma.md?via=deploy from top to bottom.

The recipe's example VM name is my-chroma. This VM's name is the output of `hostname`: use it wherever the recipe writes my-chroma. Skip the step that creates the VM; you are on it.

You are done when all of these are true. Check each one yourself:
- 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.

Read the whole recipe, including the closed details. For initial setup,
follow "Install by hand" from top to bottom, skipping VM creation:
Docker, the config and Compose files, starting Chroma, the scripts and
the exe-docs collection, the backup timer, and the restore test. The
walkthrough sections are for the owner afterwards: don't run
chroma-migrate.py, ask for a Chroma Cloud key, set up Tailscale,
integrations or Qdrant, or run the Restore or Update instructions
during initial setup. Remove only the chroma-restore-test container and
/tmp/chroma-restore that the restore test creates.
Leave the VM private and do not reboot. Finish with
https://<vm>.exe.xyz/docs/ and the answer ask.py gives to "How do I make
my VM public?".

Finish with the URLs I should open and these commands, which only I can run, from my own computer (with this VM's name in them):
  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

Also at /deploy/chroma/prompt.txt. The recipe it follows is /deploy/chroma.md.

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:

ssh my-chroma.exe.xyz 'cd chroma && uv run ask.py "How do I make my VM public?"'
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. The whole round trip takes about four seconds.

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

  • 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 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:

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):

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:

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 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:

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

Save it as EXE_TOKEN in your shell, then:

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:

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:

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 keeps the token off that VM: exe.dev adds it at the edge. On your computer, with the app's VM called my-app:

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 network; it's preinstalled. On both VMs:

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). Then, on the Chroma VM, forward port 8000 on its tailnet address to Chroma:

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 to narrow that down.

Leaving Chroma Cloud#

On October 23, 2026, Chroma announced 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:

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

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):

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:

# 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 (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:

    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 (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:

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, or send the files to a bucket on another VM.

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.

Install by hand

Create a VM#

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

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:

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:

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:

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#

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:

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

Set up nightly backups#

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:

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:

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.

Back up and restore

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:

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 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:

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 on the new VM.

The whole VM#

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.

Update Chroma

Chroma's releases are on GitHub; read the notes for every version between yours and the new one, especially migration notes. Then, on the VM, back up, change the tag, and restart:

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.

Something not working?

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

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.

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. Open-source Chroma, the same database without the hosted service, stays Apache 2.0. 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, 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; 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 in a program, or a VM-to-VM integration 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, 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 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.

Published Nov 22, 2026 · Updated Nov 22, 2026 · tested end to end Nov 22, 2026 · Markdown · manifest.json · Something wrong? Tell us