Run it locally

Prerequisites

Docker	Compose v2
Go	1.22+
Node	20+
MongoDB	on :27017, or let the bundled container start it

One command

Everything runs from the cavs-node/ package of the monorepo, not from the repository root:

cd cavs-node
cp .env.example .env      # optional — run.sh does it for you
./run.sh                  # infra + api + worker + web

Note

The repository is a monorepo: cavs-node/ is the platform (this page), and cavs-docs/ is the documentation site you’re reading, deployed separately. Every path on this page is relative to cavs-node/.

URL	What
http://localhost:5173	Dashboard
http://localhost:8080/healthz	API health
http://localhost:8080/readyz	API readiness (pings MongoDB)
http://localhost:9001	MinIO console — cavsminio / cavsminio123

Sub-commands:

./run.sh infra       # Docker services only
./run.sh services    # api + worker + web only
./run.sh down        # stop infra
./run.sh logs        # tail api and worker
./run.sh all         # everything (foregrounds the web dev server)

run.sh uses your local MongoDB if one is listening on :27017, otherwise it starts the bundled container. On boot the API creates indexes and seeds the plan catalogue — both idempotent.

What comes up

Service	Port	Notes
MongoDB	27017	Local or bundled
MinIO	9000 / 9001	S3-compatible object store; bucket cavs-cloud-dev
Pub/Sub emulator	8085	No credentials needed
Redis	6379	Optional cache
cavs-api	8080
cavs-worker	—	Health server on $PORT
cavs-web (Vite)	5173	Proxies /api to :8080

Firebase

The dashboard uses real Firebase Authentication — there is no mock. Put your project’s config in web/src/firebase-config.ts (or set the VITE_FIREBASE_* variables) and set FIREBASE_PROJECT_ID so the API verifies ID tokens against the same project.

FIREBASE_PROJECT_ID=your-firebase-project
AUTH_DEV_BYPASS=false

Caution

With AUTH_DEV_BYPASS=false the API verifies signatures and checks the issuer and audience. FIREBASE_PROJECT_ID must match your Firebase project or every real token is rejected with “invalid issuer” — the API refuses to boot in that state rather than failing mysteriously later.

Testing the API with curl

AUTH_DEV_BYPASS=true accepts unsigned tokens so you can poke the API with curl. It is backend-only (the web app always uses real Firebase) and forced off when CAVS_ENV=production.

Degraded modes

The stack is designed to still run with pieces missing:

Missing	Effect
Pub/Sub emulator	The API falls back to a no-op bus — events aren’t delivered, everything else works
Redis	Nothing; the cache is optional
MinIO / S3	Uploads and downloads fail; the control plane works
MongoDB	Nothing works — it’s the source of truth

You still need MongoDB and, for real transfers, an S3 endpoint.

Gotchas

These are the ones that actually cost time.

Ctrl-C on ./run.sh all tears down MinIO too

./run.sh all foregrounds the web dev server and installs a cleanup trap. Interrupting it sends SIGINT to the whole process group, killing MinIO, the API and the worker with it.

Symptom: every upload and download starts failing with connection refused on :9000. Check MinIO is alive before debugging anything else.

git-lfs caches push state

After a successful push, git lfs push --all won’t re-invoke the standalone agent — it prints “0 B, done” with no agent output. To exercise the agent again, push a brand-new object, or drive its NDJSON protocol directly (init / upload / terminate).

git lfs push --object-id produces spurious “Unable to stat local media path” errors; don’t rely on it.

git-lfs suppresses the agent's stderr

During a push, the agent’s [lfs-agent] … lines never reach your terminal. To see them, point the agent path at a small wrapper:

cat > /tmp/cavs-agent-wrapper.sh <<'EOF'
#!/usr/bin/env bash
exec cavs-lfs-agent "$@" 2>>/tmp/agent.err
EOF
chmod +x /tmp/cavs-agent-wrapper.sh
git config lfs.customtransfer.cavs.path /tmp/cavs-agent-wrapper.sh

Then tail -f /tmp/agent.err.

A silent finalize failure looks like a successful push

The agent reports objects complete during ingest, then mirrors and finalizes at terminate. If finalize fails, git push still succeeds — Git got its commits, and GitHub is happy. But the Hub never registered the objects: the generation doesn’t bump and no object rows appear.

Never trust the push exit code. Verify:

curl -sS "http://localhost:8080/api/v1/repositories/$REPO" -H "$H" | jq .repository.generation
curl -sS "http://localhost:8080/api/v1/repositories/$REPO/objects?limit=5" -H "$H"

The rate limiter trips pushes on repositories with many packs

The agent HEAD-guards every tree file before uploading it. Once a repository has accumulated enough packs, that burst exceeds RATE_LIMIT_RPS=30 / RATE_LIMIT_BURST=60 and the API answers 429 — and the agent does not retry or back off on 429. The mirror fails, and per the point above, silently.

For local development, raise the limits:

RATE_LIMIT_RPS=500 RATE_LIMIT_BURST=1000 ./run.sh services

This is a real robustness gap in the agent, not just a dev-environment quirk.

Vite needs the root .env for Firebase

The VITE_FIREBASE_* variables live in the cavs-node/ package root .env, not web/.env. run.sh exports them before starting Vite. A bare cd web && npm run dev starts with no Firebase config and the login page shows “Firebase not configured”.

Correct manual restart:

set -a && . ./.env && set +a && cd web && npm run dev

Unknown JSON fields are rejected

The API decodes with DisallowUnknownFields(). Any field a handler struct doesn’t declare gives 400 bad_request. If a request looks correct but fails, check every field name — this catches client changes that add a field before the server knows about it.

Restarting just the API and worker

Without disturbing MongoDB, MinIO, Redis or Pub/Sub:

pkill -f '\.run/cavs-api'
pkill -f '\.run/cavs-worker'

set -a && . ./.env && set +a
nohup .run/cavs-api    > .run/api.log    2>&1 &
nohup .run/cavs-worker > .run/worker.log 2>&1 &
disown -a

The original ./run.sh all stays alive but its tracked PIDs are now stale. A clean re-run also rebuilds the Go binaries and resets the environment.

Connecting the CLI to your local stack

cav config set api http://localhost:8080
cav login

For a plaintext-HTTP remote the transfer agent refuses to upload unless you opt in:

export CAVS_LFS_ALLOW_INSECURE_HTTP=1

Danger

Only ever set that against localhost. It disables the guard that stops your token travelling in cleartext.

Tests

cd services && go test ./...

Store integration tests are gated on MONGO_TEST_URI — a local MongoDB on :27017 works:

MONGO_TEST_URI=mongodb://localhost:27017 go test ./internal/store/...

Dashboard end-to-end tests use Playwright:

cd web && npx playwright test

Next

• Configuration reference — every variable.
• Deploying — going to production.
• Troubleshooting — symptom-first diagnosis.