Self-hosted memory and context for multi-tenant AI agents.
Point your agent at an OpenAI-compatible endpoint or add the MCP server, and IBEX resolves tenant and agent identity, injects bounded context, stores governed memories, and attempts best-effort post-response evidence for governed sessions when the PostgreSQL evidence plane is configured.
English · Español · Français · Deutsch · Português (Brasil) · 中文 · العربية
Website · Docs · Status · Benchmarks · Developer guide · Security
Most agent stacks treat memory as a vector database and identity as an afterthought. IBEX treats both as governed, tenant-scoped infrastructure.
- Identity on every call. No
org_idis accepted from a URL or browser. AuthService is the authority, and every data path filters explicitly. - Bounded context, not a prompt dump. Retrieval, ranking, and packing run under a token budget and a deadline, and degrade to directive-only context rather than blocking the proxy.
- Evidence after the response, deliberately best-effort. Governed requests attempt an evidence outbox write once the response is sent. The guarantee has a stated boundary; see Status and evidence.
![]() Overview |
![]() Sessions |
![]() Memories |
![]() Session detail |
The supported deployment is the v1-single-node profile from ADR-0097:
one self-hosted Docker Compose project, no hosted offering and no HA topology. Prerequisites are Docker Compose v2 or
Podman Compose, GNU Make, and the versions in infra/tool-versions.conf; see
TOOLCHAIN.md.
git clone https://github.com/Rick1330/ibex-harness.git
cd ibex-harness
make setup
make check-toolsGenerate the profile's secrets, start it, retrieve the one-time admin token, and prove it with an authenticated request:
make v1-secrets
make v1-up
make v1-bootstrap-pat # print the one-time bootstrap PAT
make v1-smoke # prove the profile with that PATStore the bootstrap PAT in your secret manager and remove
infra/compose/v1-single-node/bootstrap/bootstrap.pat after the smoke passes. The order matters: make v1-smoke
reads that file to authenticate, and a run without it exits 4 (skip), which the target treats as a failure — so deleting
the file first leaves the install unproven.
make v1-up rebuilds the images, waits for every required service, and prints the URL. The first start pulls the
embedding model into the tei-cache volume; pre-seed that volume for an offline or bandwidth-limited install.
make v1-down stops the profile without deleting volumes.
For a restricted sandbox or Podman machine, export the runtime so every later command sees it:
export IBEX_RUNTIME=podman
IBEX_NETWORK=host make setup # development-stack overlay; v1-single-node rejects host networkingThe scripts read IBEX_RUNTIME per process and default it to auto, which prefers Docker whenever docker info
succeeds (infra/scripts/dev-tool.sh). On a host that runs both, prefixing a single command would leave make v1-up
and make v1-smoke building and proving the profile on Docker, so export it once per shell instead. Leave
IBEX_NETWORK out of the shell environment: v1-single-node refuses host and exits 2, and the switch means something
only to the development stack.
make env-doctor diagnoses runtime, port, DNS, and telemetry issues.
The development stack is for working on the code, not for running the supported profile:
make compose-dev-up
make db-migrate
make db-seedStart AuthService and the proxy in two terminals using the commands in
DEVELOPMENT_GUIDE.md §4.4, then run the smoke test:
make dev-smokemake db-seed is local-development only; never run it against a shared environment.
pnpm install --frozen-lockfile --ignore-scripts
IBEX_OPERATOR_API_ORIGIN=https://operator.example.invalid pnpm --filter @ibex/console devOpen http://127.0.0.1:3000: a development build shows sample data. Add ?demo=0 to exercise the live path, which needs
IBEX_OPERATOR_API_ORIGIN set to a reachable operator API and fails closed without one; a production build never renders
sample data.
| Service | Runtime | What it does | Status |
|---|---|---|---|
auth/ |
Go | Token and agent validation, PAT lifecycle, provider-credential metadata | Local |
proxy/ |
Go | OpenAI-compatible LLM proxy: auth, rate limits, context injection, streaming | Local |
memory/ |
Python / FastAPI | Tenant-scoped memory writes, semantic search, dedup, conflicts, PII | Local |
context/ |
Python / gRPC | Budgeted retrieval, ranking, and packing behind a caller-token boundary | Provisional |
embedder/ |
Python | Embedding contract and backend selection | Profile-dependent |
api/ |
Python / FastAPI | Management plane: tenants, tokens, providers, policies, operator reads | Provisional |
worker/ |
Python / Celery | Extraction, erasure, billing rollups, maintenance | Mixed |
mcp-memory/ |
Python | MCP memory tools over Streamable HTTP | Partial |
mcp-operator/ |
Python | Read-only operator MCP tools | Default-off |
relay/ |
Go | Evidence outbox relay daemon | Default-off |
console/ |
Nuxt 4 + Nitro | Operator application and its server-only BFF | Provisional |
Status is a one-word signal; the status ledger carries
the evidence, the boundary, and the open gaps. The full inventory, shared packages, and local infrastructure are in
services/README.md, packages/README.md, and
infra/README.md.
The Console is the canonical operator application: a Nuxt 4 server-rendered app with a server-only BFF, covering the memory/context lifecycle — agents, sessions, memories, evidence, directives, policies, trace exploration, platform health, and settings. Incidents, drift, audit, analytics, budgets, providers, MCP tools, and access are a separate platform tier (ADR-0089).
It is read-only by design: /login exchanges a personal access token once for an HttpOnly cookie, and the Console
exposes no data mutations. Which surfaces have a live read path, and which are labelled previews, is owned by the
surface registry in services/console/shared/operator/surfaces.ts;
this README does not restate it. See services/console/README.md.
Tenant isolation is defense in depth: PostgreSQL RLS plus explicit org_id filtering on every query, with Redis keys
namespaced by org_id. Cross-tenant reads return 404, not 403, to avoid existence leaks.
Report vulnerabilities through the private process in engineering/SECURITY.md, not a
public issue.
IBEX distinguishes shipped, mounted-but-provisional, specified-not-implemented, and deferred. Local routes, schemas, fixtures, and design documents are not deployment evidence.
The authoritative runtime claim is the status ledger. Do not infer hosted readiness, measured SLOs, HA, or restore evidence from this README.
Evidence is best-effort, by design. When the PostgreSQL evidence plane is configured and the session's authoritative evidence-fence version is available, governed chat-completion requests attempt an evidence outbox write after the response; the session does not need to be closed first. Evidence may be withheld when the session or its fence is missing, or lost when persistence fails, the bounded queue is saturated, or the process shuts down before draining. The relay is default-off, so this is not a synchronous durable-before-ack guarantee.
The supported profile has been proven, not accepted. On 2026-11-15 all 13 health-checked v1-single-node
containers came up healthy, no application connection used the owner login, and a route-level cross-tenant request was
refused. That is a live cross-tenant read plus the integration suites — not a full acceptance suite, and not a
two-tenant browser journey.
- Architecture
- Development guide
- API documentation
- Environment variables
- Testing strategy
- Architecture decision records
- Security
- Contributing
Read CONTRIBUTING.md and AGENTS.md. Every commit needs a DCO sign-off
(git commit -s), and every pull request must link a tracking issue. Conventional Commits are enforced by CI.



