Quickstart (5 minutes)

Clone the repo, boot dependencies with Docker Compose, start auth and proxy, and send a protected chat request. With the default IBEX_LLM_MODE=mock, a 200 response means auth, agent verify, routing, and the mock provider all succeeded.

Prerequisites

Go 1.25+ and GNU Make
Docker Compose v2
Git (Git Bash on Windows for Make targets)
OpenAI API key — only required when IBEX_LLM_MODE=live

1. Clone and configure

.env (repo root)

git clone https://github.com/Rick1330/ibex-harness.git
cd ibex-harness
cp .env.example .env

Set IBEX_AUTH_VALIDATE_TIMEOUT=2s in services/proxy/.env (or export it) — the production 50ms budget often returns 503 on developer machines during Argon2 verification.

Leave IBEX_LLM_MODE=mock (the default) unless you intentionally want live provider calls.

2. Boot infrastructure

Terminal — repo root

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

make db-seed prints a dev PAT and agent ID. Fixed wire-form PAT from seed:

ibex_pat_00000000-0000-0000-0000-000000000004_LOCALDEVELOPMENTONLY

Org: 00000000-0000-0000-0000-000000000001 · Agent: 00000000-0000-0000-0000-000000000003

3. Start services

In separate terminals from the repo root (auth gRPC must be up before protected proxy routes):

Terminal A — auth

go run ./services/auth/cmd/auth

Terminal B — proxy

go run ./services/proxy/cmd/proxy

Optional one-shot smoke after both are running:

bash

make dev-smoke

4. Send a chat completion

Use the OpenAI-compatible path. Tenant scope comes from the PAT, not the URL:

bash

export IBEX_TEST_PAT="ibex_pat_00000000-0000-0000-0000-000000000004_LOCALDEVELOPMENTONLY"
export IBEX_TEST_AGENT_ID="00000000-0000-0000-0000-000000000003"
 
curl -s -w "\nHTTP %{http_code}\n" \
  -X POST "http://localhost:8080/v1/chat/completions" \
  -H "Authorization: Bearer ${IBEX_TEST_PAT}" \
  -H "X-IBEX-Agent-ID: ${IBEX_TEST_AGENT_ID}" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'

Expected response (mock mode)

HTTP 200 with an OpenAI-shaped JSON body from the in-process mock provider (content is a stub such as "ok"). Streaming requests ("stream": true) return SSE chunks ending with [DONE].

Live mode (optional)

bash

export IBEX_LLM_MODE=live
export OPENAI_API_KEY=sk-...
# optional: OPENAI_BASE_URL=https://api.openai.com/v1

Restart the proxy. Live mode is forbidden when IBEX_ENV=production would also allow mock — mock is disallowed in production; live requires a real key.

When you see 501

501 PROVIDER_NOT_CONFIGURED means the model id is not in the active registry (typo, or not listed / not covered by IBEX_LLM_EXTRA_MODELS). Fix the model name rather than assuming forwarding is missing.

Request flow

+--------+                         +-------+                 +------+        +----------+   
| Client |                         | Proxy |                 | Auth |        | Provider |   
+--------+                         +-------+                 +------+        +----------+   
     |                                 |                         |                 |        
     |    POST /v1/chat/completions    |                         |                 |        
     |--------------------------------->                         |                 |        
     |                                 |                         |                 |        
     |                                 |   gRPC ValidateToken    |                 |        
     |                                 |------------------------->                 |        
     |                                 |                         |                 |        
     |                                 |  org_id + permissions   |                 |        
     |                                 <.........................|                 |        
     |                                 |                         |                 |        
     |                                 |   gRPC ValidateAgent    |                 |        
     |                                 |------------------------->                 |        
     |                                 |                         |                 |        
     |                                 |  agent belongs to org   |                 |        
     |                                 <.........................|                 |        
     |                                 |                         |                 |        
     |                                 +---+                     |                 |        
     |                                 |   | rate limit + directives + normalize   |        
     |                                 <---+                     |                 |        
     |                                 |                         |                 |        
     |                                 |        mock stub or OpenAI forward        |        
     |                                 |------------------------------------------->        
     |                                 |                         |                 |        
     |                                 |                completion                 |        
     |                                 <...........................................|        
     |                                 |                         |                 |        
     |  200 (+ optional async trace)   |                         |                 |        
     <.................................|                         |                 |        
     |                                 |                         |                 |        
+--------+                         +-------+                 +------+        +----------+   
| Client |                         | Proxy |                 | Auth |        | Provider |   
+--------+                         +-------+                 +------+        +----------+

What just happened

Token validated

The proxy called auth ValidateToken over gRPC with your bearer PAT (optionally via auth cache).

Agent verified

X-IBEX-Agent-ID was checked against the org on the token.

Provider invoked

Mock mode returns a local stub; live mode forwards to the configured OpenAI-compatible API.

200 returned

Sessions/idempotency/traces may run around the response without blocking the client path.

Common issues

Symptom	Fix
`503 SERVICE_DEGRADED` on chat	Set `IBEX_AUTH_VALIDATE_TIMEOUT=2s` on proxy; ensure auth is running on `:9091`
`401` / `403` on chat	Re-run `make db-seed`; verify PAT and agent ID match seed output
`501 PROVIDER_NOT_CONFIGURED`	Use a registered model (`gpt-4o`, `gpt-4o-mini`, …) or set `IBEX_LLM_EXTRA_MODELS`
`connection refused` on `:8080`	Start proxy after auth; check `IBEX_PORT`
Compose ports in use	Stop conflicting Postgres/Redis or change compose port mappings

Full guide: Troubleshooting.

Next steps

Concepts — org, agent, and PAT model
Docker Compose — dependency stack detail
Chat completions API — request shape and headers
Provider modes — mock vs live
API errors — full error code catalog

Was this page helpful?

Prerequisites

Go 1.25+ and GNU Make
Docker Compose v2
Git (Git Bash on Windows for Make targets)
OpenAI API key — only required when IBEX_LLM_MODE=live

1. Clone and configure

.env (repo root)

git clone https://github.com/Rick1330/ibex-harness.git
cd ibex-harness
cp .env.example .env

Set IBEX_AUTH_VALIDATE_TIMEOUT=2s in services/proxy/.env (or export it) — the production 50ms budget often returns 503 on developer machines during Argon2 verification.

Leave IBEX_LLM_MODE=mock (the default) unless you intentionally want live provider calls.

2. Boot infrastructure

Terminal — repo root

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

make db-seed prints a dev PAT and agent ID. Fixed wire-form PAT from seed:

ibex_pat_00000000-0000-0000-0000-000000000004_LOCALDEVELOPMENTONLY

Org: 00000000-0000-0000-0000-000000000001 · Agent: 00000000-0000-0000-0000-000000000003

3. Start services

In separate terminals from the repo root (auth gRPC must be up before protected proxy routes):

Terminal A — auth

go run ./services/auth/cmd/auth

Terminal B — proxy

go run ./services/proxy/cmd/proxy

Optional one-shot smoke after both are running:

bash

make dev-smoke

4. Send a chat completion

Use the OpenAI-compatible path. Tenant scope comes from the PAT, not the URL:

bash

export IBEX_TEST_PAT="ibex_pat_00000000-0000-0000-0000-000000000004_LOCALDEVELOPMENTONLY"
export IBEX_TEST_AGENT_ID="00000000-0000-0000-0000-000000000003"
 
curl -s -w "\nHTTP %{http_code}\n" \
  -X POST "http://localhost:8080/v1/chat/completions" \
  -H "Authorization: Bearer ${IBEX_TEST_PAT}" \
  -H "X-IBEX-Agent-ID: ${IBEX_TEST_AGENT_ID}" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'

Expected response (mock mode)

HTTP 200 with an OpenAI-shaped JSON body from the in-process mock provider (content is a stub such as "ok"). Streaming requests ("stream": true) return SSE chunks ending with [DONE].

Live mode (optional)

bash

export IBEX_LLM_MODE=live
export OPENAI_API_KEY=sk-...
# optional: OPENAI_BASE_URL=https://api.openai.com/v1

Restart the proxy. Live mode is forbidden when IBEX_ENV=production would also allow mock — mock is disallowed in production; live requires a real key.

When you see 501

Request flow

+--------+                         +-------+                 +------+        +----------+   
| Client |                         | Proxy |                 | Auth |        | Provider |   
+--------+                         +-------+                 +------+        +----------+   
     |                                 |                         |                 |        
     |    POST /v1/chat/completions    |                         |                 |        
     |--------------------------------->                         |                 |        
     |                                 |                         |                 |        
     |                                 |   gRPC ValidateToken    |                 |        
     |                                 |------------------------->                 |        
     |                                 |                         |                 |        
     |                                 |  org_id + permissions   |                 |        
     |                                 <.........................|                 |        
     |                                 |                         |                 |        
     |                                 |   gRPC ValidateAgent    |                 |        
     |                                 |------------------------->                 |        
     |                                 |                         |                 |        
     |                                 |  agent belongs to org   |                 |        
     |                                 <.........................|                 |        
     |                                 |                         |                 |        
     |                                 +---+                     |                 |        
     |                                 |   | rate limit + directives + normalize   |        
     |                                 <---+                     |                 |        
     |                                 |                         |                 |        
     |                                 |        mock stub or OpenAI forward        |        
     |                                 |------------------------------------------->        
     |                                 |                         |                 |        
     |                                 |                completion                 |        
     |                                 <...........................................|        
     |                                 |                         |                 |        
     |  200 (+ optional async trace)   |                         |                 |        
     <.................................|                         |                 |        
     |                                 |                         |                 |        
+--------+                         +-------+                 +------+        +----------+   
| Client |                         | Proxy |                 | Auth |        | Provider |   
+--------+                         +-------+                 +------+        +----------+

What just happened

Token validated

The proxy called auth ValidateToken over gRPC with your bearer PAT (optionally via auth cache).

Agent verified

X-IBEX-Agent-ID was checked against the org on the token.

Provider invoked

Mock mode returns a local stub; live mode forwards to the configured OpenAI-compatible API.

200 returned

Sessions/idempotency/traces may run around the response without blocking the client path.

Common issues

Symptom	Fix
`503 SERVICE_DEGRADED` on chat	Set `IBEX_AUTH_VALIDATE_TIMEOUT=2s` on proxy; ensure auth is running on `:9091`
`401` / `403` on chat	Re-run `make db-seed`; verify PAT and agent ID match seed output
`501 PROVIDER_NOT_CONFIGURED`	Use a registered model (`gpt-4o`, `gpt-4o-mini`, …) or set `IBEX_LLM_EXTRA_MODELS`
`connection refused` on `:8080`	Start proxy after auth; check `IBEX_PORT`
Compose ports in use	Stop conflicting Postgres/Redis or change compose port mappings

Full guide: Troubleshooting.

Next steps

Concepts — org, agent, and PAT model
Docker Compose — dependency stack detail
Chat completions API — request shape and headers
Provider modes — mock vs live
API errors — full error code catalog

Was this page helpful?