---

What Cogentrex is

Cogentrex is a working agent control plane that you can run, study, and extend — not a toy chat wrapper around an LLM. It teaches one auditable lifecycle:

Policy → Run → Approval → Tool → Evidence → Evaluation

The runtime accepts native model tool calls, applies deterministic policy, pauses sensitive operations for human approval, executes authorized tools, and records ordered evidence. Runs can be inspected, replayed, forked, compared, grounded against documents, and evaluated later.

The goal is practical mastery: understand the architecture, trace it into real code, exercise its failure modes, and prepare for advanced agentic AI engineering roles. Cogentrex is a local learning project, not a public production service.

Architecture

Application traffic enters through a loopback-only gateway.

flowchart TB
    Browser -->|loopback only| Gateway[Unprivileged Nginx]
    Gateway --> Frontend[SvelteKit Workbench]
    Gateway --> Backend[FastAPI control plane]

    Backend --> Router[Auto / Single / Team router]
    Router --> Runtime[Typed AgentRuntime]
    Router --> Children[Bounded child runtimes]
    Children --> Runtime
    Runtime --> Provider[Model provider]
    Runtime --> Policy[Policy engine]
    Policy --> Approval[Durable approvals]
    Approval --> Tools[Secure tool registry]

    Tools --> MCP[Governed MCP]
    Tools --> Sandbox[Networkless sandbox runner]

    Runtime --> Ledger[(Run Ledger)]
    Runtime --> RAG[RAG and grounding]
    Runtime --> Eval[Evaluation and drift]

    Ledger --> Postgres[(PostgreSQL 16)]
    RAG --> Postgres
    Eval --> Postgres

    Backend --> Redis[(Redis 7)]
    Backend --> OTEL[OTEL Collector]

The sandbox is non-root, networkless, read-only, capability-free, and seccomp-constrained. Optional development tools may bind their UI to loopback.

Quick start

Requires Docker Desktop, Python 3.11+, uv, and Node.js 22+.

Run the full test suite

./scripts/verify.sh

Covers backend, frontend, browser, sandbox, container health, and benchmark preflight. No live-provider calls.

Start the local application

COGENTREX_LOCAL_PORT=80 ./scripts/local-stack.sh start
./scripts/local-stack.sh status
./scripts/local-stack.sh url

start generates ephemeral credentials, builds the managed services, and prints the loopback URL. The default is deterministic mock mode — the UI warns that no live inference occurred.

Install the optional rich learning library before the first start. It adds the decks, diagrams, audio, video, and study activities used by Present, Listen, and Study.

make media-install
COGENTREX_LOCAL_PORT=80 ./scripts/local-stack.sh start

To study real-provider behavior:

./scripts/local-stack.sh stop
COGENTREX_LOCAL_PORT=80 ./scripts/local-stack.sh start --live-provider

Live mode imports only an allowlist of COGENTREX_LLM_* settings from backend/.env. Switching modes always requires an explicit stop.

Stop and clean up:

./scripts/local-stack.sh stop

Do not invoke docker compose directly with backend/.env or dummy secrets. Use local-stack.sh so every command reuses the exact generated context.

Choose your learning path

Evidence and limitations

Start with the human evidence summary. Exact technical status lives in:

• Implementation Evidence — verified results, live-provider observations, and current scope.
• Capability Acceptance — machine-readable status of each capability.

Deliberate limits

Cogentrex does not claim:

• public or cloud deployment
• production traffic, SLOs, or on-call operations
• GPU or high-throughput model serving
• fine-tuning or training
• pgvector-backed retrieval (Cogentrex explicitly does not use pgvector)
• autonomous unapproved production optimization

These gaps are documented in Remaining Deferred Gaps.

Security boundary

Cogentrex treats the user, model, MCP output, documents, and tool arguments as untrusted input. The local host, Docker daemon, and encryption master key remain trusted boundaries. Local acceptance does not replace an independent security audit.

Project structure

backend/                 FastAPI runtime, services, persistence, and tests
frontend/                SvelteKit Workbench and browser tests
sandbox_runner/          Isolated execution service and seccomp profiles
deploy/                  Nginx and OpenTelemetry configuration
docs/                    Architecture, evidence, course, demo, and runbooks
scripts/                 Verification, deployment, backup, restore, and DR tools
docker-compose.local.yml Managed local stack definition

License

MIT — see LICENSE.

Built by Luis Valencia.