Local development
This page is for working on IBEX itself. It assumes Docker Compose is running and migrations have been applied.
1. Start dependencies
make compose-dev-up
make db-migrate
make db-seed
The Compose stack provides PostgreSQL + pgvector, Redis, ClickHouse, and MinIO. Application services run on the host.
2. Generate protobufs
make proto-gen
bash infra/scripts/context-proto-gen.sh
Run make proto-gen before Go tests that depend on generated auth/proxy protobufs. The context service has its own generation script.
3. Start auth, then proxy
# Terminal 1
POSTGRES_DSN=postgres://ibex:ibex@localhost:5432/ibex?sslmode=disable \
IBEX_GRPC_PORT=9091 \
go run ./services/auth/cmd/auth
# Terminal 2
IBEX_ENV=development \
IBEX_AUTH_GRPC_ADDR=127.0.0.1:9091 \
IBEX_AUTH_VALIDATE_TIMEOUT=2s \
REDIS_URL=redis://localhost:6379/0 \
POSTGRES_DSN=postgres://ibex:ibex@localhost:5432/ibex?sslmode=disable \
go run ./services/proxy/cmd/proxy
Why IBEX_AUTH_VALIDATE_TIMEOUT=2s locally? Argon2 verification often exceeds the production 50 ms budget on a developer machine, producing 503 SERVICE_DEGRADED before the request reaches the provider.
4. Start optional services
| Service | Needed for | Typical local port |
|---|---|---|
| Management API | Console, tenant management | 8010 |
| Memory | Memory writes, search, context | 8005 |
| Context assembly | Memory injection on chat | Pick a free gRPC port, e.g. 9092 |
| Embedder | Vector writes and search | Pick a free HTTP port |
| Worker | Extraction, deletion, billing tasks | metrics 8006, enqueue 8007 |
| MCP memory | MCP memory tools | 8090 |
| MCP operator | Read-only operator tools | 8091 |
Run Python services from their directories with uv sync --frozen --extra dev (or --group dev where the service README says so), then uvicorn or the documented entrypoint.
The context service must stay on loopback or a trusted network boundary:
PYTHONPATH=packages/proto/gen/python \
IBEX_CONTEXT_GRPC_ADDR=127.0.0.1:9092 \
services/context/.venv/bin/python -m app
5. Verify
curl -s http://localhost:8080/health
curl -s http://localhost:8080/ready
curl -s http://localhost:8081/ready
make dev-smoke
Test targets
| Target | Scope |
|---|---|
make test-proxy | Go proxy unit tests |
go test -tags=integration ./services/proxy/... | Proxy integration |
make test-auth | Auth unit tests |
make test-memory | Memory unit tests |
make test-memory-integration | Memory with PostgreSQL |
make test-context | Context tests |
make test-worker | Worker unit tests |
make test-worker-integration | Worker with PostgreSQL/Redis |
make test-embedder | Embedder tests |
make test-mcp-memory | MCP memory tests |
make test-mcp-operator | MCP operator tests |
Common local failures
| Symptom | Likely cause |
|---|---|
503 SERVICE_DEGRADED on chat | Auth too slow or unreachable |
401 after seeding | PAT and agent ID do not match seed output |
501 PROVIDER_NOT_CONFIGURED | Model not in the active registry |
relation does not exist | Migrations not applied |
| Queue tasks never run | Worker not listening to the right queue |
| Context retrieval returns fallback | Context service disabled, unavailable, or over deadline |
Rules
- Never run
db-seedagainst staging or production. - Never expose context assembly to an untrusted network.
- Never enable stdio MCP in a deployed environment.
- Never reuse Compose credentials outside local development.
- Never treat a local smoke test as hosted acceptance.