Self-host Chroma
The vector database for your RAG app, on a VM you own, before Chroma Cloud goes dark.
Shelley handles the setup. About 10 minutes.
Prefer a terminal?
curl -fsSL https://exe.dev/deploy/chroma/prompt.txt | ssh exe.dev new --prompt=/dev/stdinChroma 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-docscollection 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
https://my-chroma.exe.xyz/docs/
Chroma's API docs (Swagger UI), behind exe.dev login
https://my-chroma.exe.xyz/
The HTTP API, for programs that send an exe.dev VM token
http://localhost:8000/
The HTTP API for apps on the VM
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.dev/deploy/chroma/prompt.txt \
| ssh exe.dev new --prompt=/dev/stdinWhen 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=90dWhat Shelley is told
Set up Chroma on this VM by following the exe.dev recipe at https://exe.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 theexe-docscollection, 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-tokenheader 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.2The dashboard is at
https://my-chroma.exe.xyz:6333/dashboard, behind exe.dev login and then the key inqdrant.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.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
401frommy-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-chromaand hasn't expired.Could not connect to a Chroma serverfrom Python: through the proxy, the client needsport=443, ssl=Trueand the token header; a401looks like this too. On the VM, usehost="http://localhost:8000", and checkdocker compose ps.Could not build embedding function openai from config, orOpenAI API key is not set: setCHROMA_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 (callget_collectionwithout one), or the same model by hand.Permission deniedin 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. Lowerkeepin~/chroma/backup.sh, delete collections you don't need, or grow the disk withssh 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