Introduction

IBEX Harness is a self-hosted AI agent platform: an authenticated LLM proxy, multi-tenant identity service, and (in later phases) persistent agent memory with behavioral drift detection. The long-term goal is enterprise-grade context injection on every LLM call with under 20ms proxy overhead.

This documentation reflects what ships on main today. Auth and proxy are Phase 2 shipped; Python memory/context/dashboard services remain Phase 3+.

What you can do today

Authenticate every proxy request

Bearer PAT validation and agent identity verification over gRPC — fail-closed on auth outage.

Forward chat completions

Default IBEX_LLM_MODE=mock returns HTTP 200 from an in-process stub. Set live plus OPENAI_API_KEY for real OpenAI-compatible forwarding.

Use platform features on the critical path

Directives, sessions, idempotency keys, and auth caching are wired when Postgres/Redis are configured — see Docs hub.

Issue and revoke PATs

gRPC CreateToken / RevokeToken with Argon2id hashing, Postgres RLS, and Redis revocation publish.

Emit async traces

Optional ClickHouse writes via CLICKHOUSE_DSN — never blocks the chat path.

What does not work yet

JWT issuance and dashboard session flows
Python services: memory, context assembly, embedder, worker, API, dashboard
MinIO session archives and billing dashboards

Architecture at a glance

+-------------+             +-------+                         +--------------+
|             |             |       |                         |              |
| Agent / SDK |-HTTPS-:8080>| Proxy |       ---gRPC-:9091---->|     Auth     |
|             |             |       |                         |              |
+-------------+             +-------+                         +--------------+
                                :                                     |       
                                :                                     |       
                                :                                     |       
                                :                                     |       
                                :                                     v       
                                :                             +--------------+
                                :                             |              |
                                +---------------------------->|   Postgres   |
                                :                             |              |
                                :                             +--------------+
                                :                                             
                                :                                             
                                :                                             
                                :                                             
                                :                                             
                                :                             +--------------+
                                :                             |              |
                                +---------------------------->|    Redis     |
                                :                             |              |
                                :                             +--------------+
                                :                                             
                                :                                             
                                :                                             
                                :                                             
                                :                                             
                                :                             +--------------+
                                :                             |              |
                                +--------mock-or-live-------->| LLM provider |
                                :                             |              |
                                :                             +--------------+
                                :                                             
                                :                                             
                                :                                             
                                :                                             
                                :                                             
                                :                             +--------------+
                                :                             |              |
                                +............async...........>|  ClickHouse  |
                                                              |              |
                                                              +--------------+

Component	Status	Port (default)
Proxy	Shipped — auth, rate limit, mock/live forward, sessions, directives	HTTP 8080
Auth	Shipped — PAT + agent identity + revoke publish	HTTP 8081, gRPC 9091
Postgres	Running via Compose	5432
Redis	Running via Compose	6379
ClickHouse	Optional traces when DSN set	8123 / 9002
Memory / Context	Not implemented (Phase 3)	—

Deeper dive: Architecture and Request lifecycle.

New contributor path

Prerequisites

Docker, GNU Make, Go 1.25+, Buf CLI. See TOOLCHAIN in the roadmap reference.

Clone and boot infra

make compose-dev-up && make db-migrate && make db-seed

Generate protos

make proto-gen — required before go test on auth/proxy.

Start auth then proxy

Auth gRPC must be up before protected proxy routes work.

Smoke test

make dev-smoke — health, auth failures, and mock chat success.

Set IBEX_AUTH_VALIDATE_TIMEOUT=2s on the proxy locally — the production 50ms budget often triggers 503 on developer machines during Argon2 verification.

Security invariants

Security is not deferred to a later phase:

Multi-tenant isolation via RLS + explicit org filters — Tenant isolation
Cross-tenant resource access returns 403, never 404
PAT secrets hashed with Argon2id; plaintext shown once — Secrets and keys
ClickHouse queries must filter org_id (no RLS there)
35+ automated security integration cases in CI

Overview: Security.

Verify the proxy is up

After make compose-dev-up, migrations, and seed:

bash

curl -s http://localhost:8080/health
curl -s http://localhost:8080/ready

Expected: HTTP 200 on /health. /ready reports ok when auth gRPC and Redis are reachable.

Protected probe (requires seeded credentials):

bash

curl -s http://localhost:8080/v1/internal/auth-probe \
  -H "Authorization: Bearer ${IBEX_DEV_TOKEN}" \
  -H "X-IBEX-Agent-ID: ${IBEX_DEV_AGENT_ID}"

Documentation map

Section	Start here
Run locally in 5 minutes	Quickstart
Org, agent, token model	Concepts
Proxy middleware and endpoints	Proxy overview
PAT issuance	Issuing API keys
Error codes	API errors
Implementation progress	Roadmap

Next steps

Quickstart — clone, boot, and send a mock chat request
Concepts — organizations, agents, and tokens
FAQ — common setup questions
Proxy overview — middleware pipeline detail

Was this page helpful?

This documentation reflects what ships on main today. Auth and proxy are Phase 2 shipped; Python memory/context/dashboard services remain Phase 3+.

What you can do today

Authenticate every proxy request

Bearer PAT validation and agent identity verification over gRPC — fail-closed on auth outage.

Forward chat completions

Default IBEX_LLM_MODE=mock returns HTTP 200 from an in-process stub. Set live plus OPENAI_API_KEY for real OpenAI-compatible forwarding.

Use platform features on the critical path

Directives, sessions, idempotency keys, and auth caching are wired when Postgres/Redis are configured — see Docs hub.

Issue and revoke PATs

gRPC CreateToken / RevokeToken with Argon2id hashing, Postgres RLS, and Redis revocation publish.

Emit async traces

Optional ClickHouse writes via CLICKHOUSE_DSN — never blocks the chat path.

What does not work yet

JWT issuance and dashboard session flows
Python services: memory, context assembly, embedder, worker, API, dashboard
MinIO session archives and billing dashboards

Architecture at a glance

+-------------+             +-------+                         +--------------+
|             |             |       |                         |              |
| Agent / SDK |-HTTPS-:8080>| Proxy |       ---gRPC-:9091---->|     Auth     |
|             |             |       |                         |              |
+-------------+             +-------+                         +--------------+
                                :                                     |       
                                :                                     |       
                                :                                     |       
                                :                                     |       
                                :                                     v       
                                :                             +--------------+
                                :                             |              |
                                +---------------------------->|   Postgres   |
                                :                             |              |
                                :                             +--------------+
                                :                                             
                                :                                             
                                :                                             
                                :                                             
                                :                                             
                                :                             +--------------+
                                :                             |              |
                                +---------------------------->|    Redis     |
                                :                             |              |
                                :                             +--------------+
                                :                                             
                                :                                             
                                :                                             
                                :                                             
                                :                                             
                                :                             +--------------+
                                :                             |              |
                                +--------mock-or-live-------->| LLM provider |
                                :                             |              |
                                :                             +--------------+
                                :                                             
                                :                                             
                                :                                             
                                :                                             
                                :                                             
                                :                             +--------------+
                                :                             |              |
                                +............async...........>|  ClickHouse  |
                                                              |              |
                                                              +--------------+

Component	Status	Port (default)
Proxy	Shipped — auth, rate limit, mock/live forward, sessions, directives	HTTP 8080
Auth	Shipped — PAT + agent identity + revoke publish	HTTP 8081, gRPC 9091
Postgres	Running via Compose	5432
Redis	Running via Compose	6379
ClickHouse	Optional traces when DSN set	8123 / 9002
Memory / Context	Not implemented (Phase 3)	—

Deeper dive: Architecture and Request lifecycle.

New contributor path

Prerequisites

Docker, GNU Make, Go 1.25+, Buf CLI. See TOOLCHAIN in the roadmap reference.

Clone and boot infra

make compose-dev-up && make db-migrate && make db-seed

Generate protos

make proto-gen — required before go test on auth/proxy.

Start auth then proxy

Auth gRPC must be up before protected proxy routes work.

Smoke test

make dev-smoke — health, auth failures, and mock chat success.

Set IBEX_AUTH_VALIDATE_TIMEOUT=2s on the proxy locally — the production 50ms budget often triggers 503 on developer machines during Argon2 verification.

Security invariants

Security is not deferred to a later phase:

Multi-tenant isolation via RLS + explicit org filters — Tenant isolation
Cross-tenant resource access returns 403, never 404
PAT secrets hashed with Argon2id; plaintext shown once — Secrets and keys
ClickHouse queries must filter org_id (no RLS there)
35+ automated security integration cases in CI

Overview: Security.

Verify the proxy is up

After make compose-dev-up, migrations, and seed:

bash

curl -s http://localhost:8080/health
curl -s http://localhost:8080/ready

Expected: HTTP 200 on /health. /ready reports ok when auth gRPC and Redis are reachable.

Protected probe (requires seeded credentials):

bash

curl -s http://localhost:8080/v1/internal/auth-probe \
  -H "Authorization: Bearer ${IBEX_DEV_TOKEN}" \
  -H "X-IBEX-Agent-ID: ${IBEX_DEV_AGENT_ID}"

Documentation map

Section	Start here
Run locally in 5 minutes	Quickstart
Org, agent, token model	Concepts
Proxy middleware and endpoints	Proxy overview
PAT issuance	Issuing API keys
Error codes	API errors
Implementation progress	Roadmap

Next steps

Quickstart — clone, boot, and send a mock chat request
Concepts — organizations, agents, and tokens
FAQ — common setup questions
Proxy overview — middleware pipeline detail

Was this page helpful?