Skip to content

Quickstart

  • Start the stack

    Bring up Postgres + Neo4j + API + UI with one command.

  • Verify readiness

    Confirm /api/ready is green before indexing or querying.

  • Index your first corpus

    Index a folder on disk into chunks/embeddings (and optional graph context).

  • Search

    Run tri-brid retrieval (vector + sparse + graph) and inspect results before moving into eval/tracing workflows.

User manual UI tour API reference

Default dev URLs

  • UI: http://127.0.0.1:5173/web
  • API: http://127.0.0.1:8012/api

Ports are configurable

./start.sh honors BACKEND_PORT and FRONTEND_PORT. If you change ports, update your curl examples accordingly.

1) Start everything

From the repo root:

./start.sh

Optional: add observability (Prometheus/Grafana/Loki) if you’re going to tune or benchmark:

./start.sh --with-observability

Advanced: on Apple Silicon, you can run Postgres natively (skip Docker postgres) for lower overhead:

./start.sh --native-postgres

See Native Postgres (macOS) for setup steps.

2) Verify the API is ready

curl -sS "http://127.0.0.1:8012/api/ready" | jq .
curl -sS "http://127.0.0.1:8012/api/health" | jq .

If readiness is failing, jump to Troubleshooting.

ragweld can run without every provider key, but many features (embeddings, generation, cloud reranking) require at least one provider configured.

curl -sS "http://127.0.0.1:8012/api/secrets/check?keys=OPENAI_API_KEY,ANTHROPIC_API_KEY" | jq .

You can also see this in the UI at Admin → Secrets.

4) Index your first corpus

Pick a folder on disk and a stable corpus id (lowercase slug).

BASE="http://127.0.0.1:8012/api"

curl -sS -X POST "$BASE/index" \
  -H "Content-Type: application/json" \
  -d '{
    "corpus_id": "demo",
    "repo_path": "/absolute/path/to/your/project",
    "force_reindex": false
  }' | jq .

import httpx

BASE = "http://127.0.0.1:8012/api"
req = {
    "corpus_id": "demo",
    "repo_path": "/absolute/path/to/your/project",
    "force_reindex": False,
}
httpx.post(f"{BASE}/index", json=req, timeout=30).raise_for_status()

Graph is optional

If you haven’t configured Neo4j (or you want faster bring-up), you can still index and search using the Postgres-backed legs. Graph retrieval will degrade gracefully when unavailable.

5) Watch indexing progress

curl -sS "http://127.0.0.1:8012/api/index/demo/status" | jq .

When status becomes complete, you’re ready to search.

BASE="http://127.0.0.1:8012/api"

curl -sS -X POST "$BASE/search" \
  -H "Content-Type: application/json" \
  -d '{
    "corpus_id": "demo",
    "query": "Where is indexing started in the backend?",
    "top_k": 8
  }' | jq '.matches | length'

import httpx

BASE = "http://127.0.0.1:8012/api"
payload = {"corpus_id": "demo", "query": "Where is indexing started?", "top_k": 8}
res = httpx.post(f"{BASE}/search", json=payload, timeout=30).json()
print([(m["file_path"], m["score"]) for m in res.get("matches", [])])

Next steps