Skip to content

Tutorial: Five-minute gateway

In five minutes you will have a local Aegis gateway running, make a governed chat request through it, and inspect the audit log.

Prerequisites

  • Python 3.11+
  • uv (recommended) or pip

1. Install

pip install aegis-gateway

2. Initialise

aegis init          # writes aegis.yaml in the current directory

The generated aegis.yaml enables PII masking and leaves everything else as commented examples. For this tutorial, replace its contents with the minimal working config below:

providers:
  demo:
    type: openai_compatible
    base_url: http://localhost:8000/v1
    api_key: demo

routes:
  default:
    provider: demo

3. Start the dev server

aegis dev           # binds localhost:8000, no auth, FakeProvider

The dev command always uses FakeProvider — a safe in-memory provider that returns a canned response without making any real model calls. Leave this terminal running.

4. Send a governed chat request

In a second terminal:

curl -s http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"default","messages":[{"role":"user","content":"Hello!"}]}' \
  | python3 -m json.tool

You will see an OpenAI-compatible response. Every request passes through the Aegis pipeline — ingress guards, route resolution, execution, egress guards — even with FakeProvider.

5. Check the audit log

curl -s http://localhost:8000/v1/audit | python3 -m json.tool

The runs array contains one entry for every request, with status, principal, route, and verdict events.

Next steps