Quickstart

Quick setup with Claude Code, Cursor, Codex, etc.

The fastest path to a working Compass integration is to paste the prompt below into your AI coding assistant. It tells the agent to read your codebase, work out where your data lives and what you’re trying to index, ask you any clarifying questions it needs, and then propose concrete integration code for your stack.

Copy setup prompt

You are helping me integrate Compass, a self-hosted vector + full-text search engine built for multimodal video and metadata-driven retrieval. Compass docs: https://docs.runcaptain.com/guides/compass/overview
Before writing any code, do the following.
1. Read my codebase. Identify:
   - Where my data lives (GCS, S3, local files, a database, somewhere else)
   - The content format (video files, JSON sidecars, PDFs, transcripts, images, plain text)
   - Whether I already have an embedding pipeline (OpenAI, Gemini, HuggingFace TEI, BGE, custom GPU server)
   - What search or retrieval code I have today (vector DB, ElasticSearch, in-memory, nothing yet)
   - Whether I am self-hosting Compass or using a Captain-hosted endpoint
2. Check Compass freshness:
   - If I have `COMPASS_BASE_URL` set, call `GET $COMPASS_BASE_URL/health` and read the returned `version`.
   - If I pasted a saved `COMPASS-SETUP.md` or `compass-skill.md`, compare its listed version to live `/health`.
   - If the versions differ, treat the saved setup file as stale. Prefer the live API response plus current docs over embedded examples in the saved file.
3. Ask me any questions you need answered that are not visible in the codebase. Start with:
   - **Hosted or self-hosted?** Do I want Compass Cloud (managed by Captain, included with a Captain enterprise license; if I don't have one, talk to sales at https://runcaptain.com/contact) or do I want to self-host the Docker container from https://github.com/runcaptain/compass on my own infrastructure?
   - Compass base URL and API key (I will set COMPASS_BASE_URL and COMPASS_API_KEY in my env once we've chosen above)
   - Collection name(s) to use
   - Which embedding models to register as vector spaces (BGE-small for text, Qwen3-VL for multimodal, my own GPU endpoint, etc.)
   - Whether I want full-text, semantic, or hybrid search
   - Whether my data follows the TAMS hierarchy (Source → Flow → Segment) for time-range queries on video
   - Whether I have sidecar JSON metadata to embed, filter on, or both
4. After my answers, propose a concrete plan:
   - Collection creation call (POST /collections with the vector spaces I picked)
   - Ingest code in my language, with my actual data source, chunking strategy, and metadata shape
   - Search code with the right mode, vector_space selection, filters, and recency settings
   - If TAMS applies, parent-child wiring with client_id, parent_ref, group_id
   - If sidecars apply, the URI-in-metadata pattern and either stringify-and-embed or flatten-to-prose
5. Stop and confirm the plan with me before writing any files. Once I approve, write the code.
Reference docs (fetch the llms.txt index first, then individual pages as needed; append `.md` to any page URL for clean markdown):
- https://docs.runcaptain.com/llms.txt
- https://docs.runcaptain.com/guides/compass/overview
- https://docs.runcaptain.com/guides/compass/quickstart
- https://docs.runcaptain.com/guides/compass/multiple-embedding-models
- https://docs.runcaptain.com/guides/compass/filters-recency-boosts
- https://docs.runcaptain.com/guides/compass/tams-and-time-range-search
- https://docs.runcaptain.com/guides/compass/upgrading-models

If you prefer to wire it up by hand, the rest of this page walks through the same flow manually.

Manual setup

You’ll:

Create a collection with two vector spaces (text + multimodal)
Ingest one video segment into both spaces
Run a hybrid query across both and read the score breakdown

Set your deployment URL and API key once. The rest of the page references them as $COMPASS_BASE_URL and $COMPASS_API_KEY:

$ export COMPASS_BASE_URL="https://api.your-org.runcaptain.com"
$ export COMPASS_API_KEY="your-compass-key"

Every request to a hosted Compass deployment is authenticated with a bearer token. Send Authorization: Bearer $COMPASS_API_KEY on every call. The examples below include it.

Check your Compass version

Compass exposes its running version from the health endpoint:

$ curl "$COMPASS_BASE_URL/health" \
>   -H "Authorization: Bearer $COMPASS_API_KEY"

If you use an agent setup file from the Compass Console, compare the version returned by /health with the Version: listed in that file. If they differ, the setup file may still have useful credentials, but its embedded examples may be stale. Fetch the current docs before coding:

1. Create the collection

Create a collection named media with two named vector spaces: harrier for text search and qwen3-vl for cross-modal search on video frames.

$ curl -X POST $COMPASS_BASE_URL/collections \
>   -H "Authorization: Bearer $COMPASS_API_KEY" \
>   -H 'Content-Type: application/json' \
>   -d '{
>     "name": "media",
>     "vector_spaces": {
>       "harrier": {
>         "dims": 768,
>         "model": "microsoft/harrier-oss-v1-0.6b",
>         "status": "active"
>       },
>       "qwen3-vl": {
>         "dims": 896,
>         "model": "Qwen/Qwen3-VL-Embedding-2B",
>         "status": "active"
>       }
>     }
>   }'

2. Ingest a segment

Each chunk targets one vector space. Ingest a single segment twice: once as a text chunk (transcript) and once as a visual chunk (frame embedding). Both reference the same parent source via parent_ref.

$ curl -X POST $COMPASS_BASE_URL/collections/media/ingest \
>   -H "Authorization: Bearer $COMPASS_API_KEY" \
>   -H 'Content-Type: application/json' \
>   -d '{
>     "chunks": [
>       {
>         "client_id": "seg-001-text",
>         "file_id": "asset-001",
>         "chunk_index": 0,
>         "doc_type": "segment",
>         "parent_ref": "src-001",
>         "group_id": "src-001",
>         "text": "Goal celebration. Striker runs toward the corner flag, arms wide.",
>         "vector_space": "harrier",
>         "metadata": {
>           "timerange_start_ms": 2040000,
>           "timerange_end_ms": 2055000,
>           "shot_type": "wide",
>           "scene": "celebration"
>         }
>       },
>       {
>         "client_id": "seg-001-visual",
>         "file_id": "asset-001",
>         "chunk_index": 0,
>         "doc_type": "segment",
>         "parent_ref": "src-001",
>         "group_id": "src-001",
>         "text": "Goal celebration. Striker runs toward the corner flag, arms wide.",
>         "vector_space": "qwen3-vl",
>         "metadata": {
>           "timerange_start_ms": 2040000,
>           "timerange_end_ms": 2055000,
>           "shot_type": "wide",
>           "scene": "celebration"
>         }
>       }
>     ]
>   }'

Both chunks share the same file_id, chunk_index, and group_id but target different vector spaces. This is how Compass stores the same content in multiple embedding spaces.

3. Run a hybrid multimodal query

Search both vector spaces at once. Compass runs BM25 against the text index, HNSW against each named vector space, merges all three result sets via RRF, and returns a single ranked list.

$ curl -X POST $COMPASS_BASE_URL/collections/media/search \
>   -H "Authorization: Bearer $COMPASS_API_KEY" \
>   -H 'Content-Type: application/json' \
>   -d '{
>     "query": "goal celebration slow motion",
>     "mode": "hybrid",
>     "vector_space": ["harrier", "qwen3-vl"],
>     "top_k": 5
>   }'

Response:

1 {
2   "results": [
3     {
4       "chunk": {
5         "id": 42,
6         "file_id": "asset-001",
7         "chunk_index": 0,
8         "doc_type": "segment",
9         "text": "Goal celebration. Striker runs toward the corner flag, arms wide.",
10         "metadata": {
11           "timerange_start_ms": 2040000,
12           "timerange_end_ms": 2055000,
13           "shot_type": "wide",
14           "scene": "celebration"
15         },
16         "group_id": "src-001"
17       },
18       "score": 0.94,
19       "source": "both",
20       "parent_metadata": {
21         "asset_type": "video",
22         "title": "Premier League: Arsenal vs Chelsea"
23       }
24     }
25   ],
26   "total": 1,
27   "took_us": 18000,
28   "mode": "hybrid"
29 }

source tells you which retriever found the hit ("fts", "semantic", or "both"). score is the final value after RRF and any scoring boosts. parent_metadata is available in v0.3 and later, populated when the hit is a segment whose parent source (referenced by parent_ref) exists in the collection.

4. Scope to a single space

If you know the query is visual, skip the text space entirely:

$ curl -X POST $COMPASS_BASE_URL/collections/media/search \
>   -H "Authorization: Bearer $COMPASS_API_KEY" \
>   -H 'Content-Type: application/json' \
>   -d '{
>     "query": "striker near corner flag",
>     "mode": "semantic",
>     "vector_space": "qwen3-vl",
>     "top_k": 5
>   }'

Pass a string (not an array) to vector_space when you want a single space. Pass an array when you want RRF across multiple spaces.