ibexharness
DocsBlogReleasesRoadmap
GitHub
ibexharness

Documentation

IntroductionQuickstart (5 minutes)ConceptsFAQ
Getting Started›Quickstart (5 minutes)
Getting Started

Quickstart (5 minutes)

Run IBEX Harness locally and send your first proxied request in about five minutes.

Clone the repo, boot dependencies with Docker Compose, start auth and proxy, and send a protected chat request. A 501 response means Phase 1 succeeded — auth, agent verify, and routing worked; provider forwarding ships in Phase 2.

Docker must be running with ports 8080, 8081, 9091, 5432, and 6379 free. Stuck? See Troubleshooting.

Prerequisites

  • Go 1.25+ and GNU Make
  • Docker Compose v2
  • Git (Git Bash on Windows for Make targets)
  • OpenAI API key — optional until Phase 2; not used by the Phase 1 probe

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.

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 (auth gRPC must be up before protected proxy routes):

Terminal A — auth
cd services/auth && go run .
Terminal B — proxy
cd services/proxy && go run .

Optional one-shot smoke after both are running:

bash
make dev-smoke

4. Probe a protected route

Send an OpenAI-shaped chat request to the org-scoped path. Export credentials from seed output or use the fixed dev values:

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/orgs/00000000-0000-0000-0000-000000000001/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

HTTP 501 with a JSON error envelope:

JSON
{
  "error": {
    "code": "PROVIDER_NOT_CONFIGURED",
    "message": "No LLM provider adapter is configured for this deployment",
    "request_id": "01HXXXXXXXXXXXXXXXXXXXX"
  }
}

501 means success in Phase 1

Token validation, agent verification, body normalization, and routing all succeeded. The proxy intentionally stops before calling an LLM provider.

Request flow

Mermaid diagram: sequenceDiagram
+--------+                                 +-------+                 +------+  +----------+   
| Client |                                 | Proxy |                 | Auth |  | Provider |   
+--------+                                 +-------+                 +------+  +----------+   
     |                                         |                         |           |        
     |  POST /v1/orgs/{org}/chat/completions   |                         |           |        
     |----------------------------------------->                         |           |        
     |                                         |                         |           |        
     |                                         |   gRPC ValidateToken    |           |        
     |                                         |------------------------->           |        
     |                                         |                         |           |        
     |                                         |  org_id + permissions   |           |        
     |                                         <.........................|           |        
     |                                         |                         |           |        
     |                                         |   gRPC ValidateAgent    |           |        
     |                                         |------------------------->           |        
     |                                         |                         |           |        
     |                                         |  agent belongs to org   |           |        
     |                                         <.........................|           |        
     |                                         |                         |           |        
     |                                         +---+                     |           |        
     |                                         |   | rate limit + normalize JSON     |        
     |                                         <---+                     |           |        
     |                                         |                         |           |        
     |                                         |     +------------------------+      |        
     |                                         |     | Phase 2+ forwards here |      |        
     |                                         |     +------------------------+      |        
     |                                         |                         |           |        
     |       501 PROVIDER_NOT_CONFIGURED       |                         |           |        
     <.........................................|                         |           |        
     |                                         |                         |           |        
+--------+                                 +-------+                 +------+  +----------+   
| Client |                                 | Proxy |                 | Auth |  | Provider |   
+--------+                                 +-------+                 +------+  +----------+

What just happened

1

Token validated

The proxy called auth ValidateToken over gRPC with your bearer PAT.

2

Agent verified

X-IBEX-Agent-ID was checked against the org in the URL path.

3

Body normalized

JSON was parsed per ADR-0012; provider forwarding is deferred to Phase 2.

4

501 returned

No provider adapter is registered — expected until Phase 2.

Common issues

SymptomFix
503 SERVICE_DEGRADED on chatSet IBEX_AUTH_VALIDATE_TIMEOUT=2s on proxy; ensure auth is running on :9091
401 / 403 on chatRe-run make db-seed; verify PAT and agent ID match seed output
connection refused on :8080Start proxy after auth; check IBEX_PORT
Compose ports in useStop 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 — 501 contract and headers
  • API errors — full error code catalog

Was this page helpful?

Edit on GitHub

Last updated on

PreviousIntroductionNextConcepts

On this page

  • Prerequisites
  • 1. Clone and configure
  • 2. Boot infrastructure
  • 3. Start services
  • 4. Probe a protected route
  • Expected response
  • Request flow
  • What just happened
  • Common issues
  • Next steps
0%