Module 0: Setup & orientation#

You are in the CPEX tutorial. This module gets you oriented and checks your setup. It changes nothing on your system.

Goal: understand what CPEX is, confirm your toolchain, and know which modules need the IdP.

What CPEX is#

CPEX is a policy enforcement runtime for AI agents. It is a deterministic reference monitor between an agent and every capability it invokes: tools, prompts, resources, inference providers. Each capability defines its own enforcement pipeline (authorization, delegation, redaction, information-flow control, audit), written declaratively in APL and run at the boundary.

You are the host: the process that embeds CPEX and drives the loop of resolving identity, running policy, calling the backend, and running policy again on the result. The tutorial harness wraps that loop in a single mediate() call so you can focus on policy. Module 9 opens mediate() up and shows the real dispatch API underneath.

Get the code#

The tutorial runs from a clone of the CPEX repository (not from a published crate), so you can edit the policies and examples as you go.

Install Rust 1.96 or newer with rustup (gives you rustc and cargo).

Clone the repo and move into it:

git clone https://github.com/contextforge-org/cpex.git
cd cpex

Run every cargo run -p cpex-tutorial ... command from the repository root.

Check your setup#

cargo run -p cpex-tutorial --example m00_setup

The crate builds, and you are told whether the IdP is up:

=== Module 0: Setup & orientation ===
...
Checking the tutorial IdP (Keycloak) ... not running
Modules 0–1 work without it. For module 2 onward, start it:
  docker compose -f examples/tutorial/idp/docker-compose.yml up -d

The IdP#

From module 2 on, the tutorial resolves real JWTs from a Keycloak realm. Identity, token exchange, and JWKS validation are core to what CPEX enforces, so mocking them would teach a fake shape of the problem. Starting it is one command:

docker compose -f examples/tutorial/idp/docker-compose.yml up -d   # about 30s on first boot

The realm is imported on start and lives only in the container. docker compose ... down wipes it, which is also your reset button. Every credential in it is tutorial-only. Never reuse them. See idp/README.md for the personas.

You do not need it yet. Modules 0 and 1 run on Rust alone.

Checkpoint#

Who runs the enforcement loop, CPEX or your application?

Your application (the host). CPEX is a library you embed at the boundary. It evaluates and enforces policy, but the host owns the loop that calls it. The tutorial's `mediate()` is that loop.

Why a real Keycloak instead of a mock?

Identity resolution, token exchange, and JWKS-based validation are central to what CPEX does. A mock would let you write policy against a shape that does not match reality. The realm is small and disposable, so the cost is one `docker compose up`.

Next#

Module 1: Hello, enforcement: the smallest CPEX host, and your first allow and deny.