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 today — not the full vision. Phase 1 delivered auth + proxy; Phase 1.5 delivers this docs site. LLM forwarding and memory services are explicitly out of scope until Phase 2+.

What you can do today

Authenticate every proxy request

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

Run the stack locally

Docker Compose for Postgres and Redis; auth and proxy on the host for fast iteration.

Enforce org rate limits

Redis-backed RPM budgets per organization (fail-open when Redis is down).

Issue and revoke PATs

gRPC CreateToken / RevokeToken with Argon2id hashing and Postgres RLS.

Browse this docs site

Search, OG previews, ADR index, and roadmap with Phase honesty throughout.

What does not work yet

Per current state and the development guide:

JWT issuance and dashboard session flows
Proxy LLM forwarding and context injection
Python services: memory, context assembly, embedder, worker, API, dashboard
Background jobs, ClickHouse trace ingestion, MinIO session archives

Architecture at a glance

+-------------+             +-------+                    +--------------+     +----------+
|             |             |       |                    |              |     |          |
| Agent / SDK |-HTTPS-:8080>| Proxy |    --gRPC-:9091--->|     Auth     |---->| Postgres |
|             |             |       |                    |              |     |          |
+-------------+             +-------+                    +--------------+     +----------+
                                :                                                         
                                :                                                         
                                :                                                         
                                :                                                         
                                :                                                         
                                :                        +--------------+                 
                                :                        |              |                 
                                +----------------------->|    Redis     |                 
                                :                        |              |                 
                                :                        +--------------+                 
                                :                                                         
                                :                                                         
                                :                                                         
                                :                                                         
                                :                                                         
                                :                        +--------------+                 
                                :                        |              |                 
                                +........Phase.2........>| LLM provider |                 
                                                         |              |                 
                                                         +--------------+

Component	Phase 1 status	Port (default)
Proxy	Running — auth, validate, rate limit	HTTP 8080
Auth	Running — PAT + agent identity	HTTP 8081, gRPC 9091
Postgres	Running via Compose	5432
Redis	Running via Compose	6379
Memory / Context	Not implemented	—

Deeper dive: Architecture and Request lifecycle.

New contributor path

The development guide targets a one-hour onboarding loop:

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, 501 chat stub.

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
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 probe request
Concepts — organizations, agents, and tokens
FAQ — common setup questions
Proxy overview — middleware pipeline detail

Was this page helpful?

What you can do today

Authenticate every proxy request

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

Run the stack locally

Docker Compose for Postgres and Redis; auth and proxy on the host for fast iteration.

Enforce org rate limits

Redis-backed RPM budgets per organization (fail-open when Redis is down).

Issue and revoke PATs

gRPC CreateToken / RevokeToken with Argon2id hashing and Postgres RLS.

Browse this docs site

Search, OG previews, ADR index, and roadmap with Phase honesty throughout.

What does not work yet

Per current state and the development guide:

JWT issuance and dashboard session flows
Proxy LLM forwarding and context injection
Python services: memory, context assembly, embedder, worker, API, dashboard
Background jobs, ClickHouse trace ingestion, MinIO session archives

Architecture at a glance

+-------------+             +-------+                    +--------------+     +----------+
|             |             |       |                    |              |     |          |
| Agent / SDK |-HTTPS-:8080>| Proxy |    --gRPC-:9091--->|     Auth     |---->| Postgres |
|             |             |       |                    |              |     |          |
+-------------+             +-------+                    +--------------+     +----------+
                                :                                                         
                                :                                                         
                                :                                                         
                                :                                                         
                                :                                                         
                                :                        +--------------+                 
                                :                        |              |                 
                                +----------------------->|    Redis     |                 
                                :                        |              |                 
                                :                        +--------------+                 
                                :                                                         
                                :                                                         
                                :                                                         
                                :                                                         
                                :                                                         
                                :                        +--------------+                 
                                :                        |              |                 
                                +........Phase.2........>| LLM provider |                 
                                                         |              |                 
                                                         +--------------+

Component	Phase 1 status	Port (default)
Proxy	Running — auth, validate, rate limit	HTTP 8080
Auth	Running — PAT + agent identity	HTTP 8081, gRPC 9091
Postgres	Running via Compose	5432
Redis	Running via Compose	6379
Memory / Context	Not implemented	—

Deeper dive: Architecture and Request lifecycle.

New contributor path

The development guide targets a one-hour onboarding loop:

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, 501 chat stub.

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
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 probe request
Concepts — organizations, agents, and tokens
FAQ — common setup questions
Proxy overview — middleware pipeline detail

Was this page helpful?