Docs · Quickstart

Get running in five minutes

Aurora-Lens runs as a proxy between your application and any LLM. Your application points at Aurora-Lens instead of the model directly. Everything else stays the same.

Step 1

Install

Requires Python 3.10+. Install the proxy extras:

pip install "aurora-lens[proxy]"

If you want spaCy-based extraction (recommended for production):

pip install "aurora-lens[proxy]"
python -m spacy download en_core_web_sm

Step 2

Configure

Create a file called aurora-lens.yaml. The minimal configuration is:

upstream:
  provider: openai
  api_key: ${OPENAI_API_KEY}
  model: gpt-4o-mini

governance:
  policy: strict
  audit_log: ./audit.jsonl

To use a different provider or a locally-hosted model, set base_url:

upstream:
  provider: openai
  api_key: ${OPENAI_API_KEY}
  model: llama-3.1-8b-instant
  base_url: https://api.groq.com/openai/v1

The ${OPENAI_API_KEY} syntax reads from your environment at startup. You can also paste the key directly, or set AURORA_LENS_UPSTREAM_API_KEY as an environment variable and omit api_key from the file entirely.

Step 3

Start the proxy

aurora-lens proxy -c aurora-lens.yaml

The proxy starts on http://localhost:8080 by default. To change the port:

aurora-lens proxy -c aurora-lens.yaml --port 9000

To run without a config file, set environment variables instead:

AURORA_LENS_UPSTREAM_PROVIDER=openai \
AURORA_LENS_UPSTREAM_MODEL=gpt-4o-mini \
AURORA_LENS_GOV_POLICY=strict \
aurora-lens proxy

Step 4

Point your application at the proxy

Aurora-Lens exposes an OpenAI-compatible endpoint. Change your application's base URL from the model provider to Aurora-Lens:

# Before
client = OpenAI(base_url="https://api.openai.com/v1")

# After — no other changes needed
client = OpenAI(base_url="http://localhost:8080/v1", api_key="any")

The proxy forwards admitted requests to the upstream model and intercepts everything else before it reaches your application.

Step 5

Verify

Check the proxy is running and the audit log is writable:

curl http://localhost:8080/health

You should see "status": "ok" and "audit_writable": true.

Send a request through your application as normal. Then inspect the last audit entry:

curl http://localhost:8080/v1/audit/recent?n=1

Each entry records the outcome (ADMIT, ASK, REFUSE, or STOP), the flags that fired, the policy applied, and the hash-chained audit ID.

Configuration reference

Policy modes

Set under governance.policy in the YAML, or via AURORA_LENS_GOV_POLICY.

Mode	Behaviour
strict	Default. Flags trigger hard stops and refusals. Recommended for regulated domains.
moderate	Warnings flag for revision rather than stopping. Suitable for supervised deployments.
open	Flags are logged but output is not blocked. For monitoring-only deployments.

Authority class

Set under governance.authority_class. Controls thresholds in high-stakes domains.

Class	Meaning
GP	General purpose. Default. Standard thresholds apply.
DA	Domain authorised. Elevated permissions for credentialed professional contexts.
HS	Human supervised. Highest permissions — human in the loop confirmed.

Minimal production YAML

upstream:
  provider: openai
  api_key: ${OPENAI_API_KEY}
  model: gpt-4o

listen:
  host: 0.0.0.0
  port: 8080

governance:
  policy: strict
  authority_class: GP
  audit_log: /data/audit.jsonl
  audit_backend: ledger

extraction:
  backend: spacy

Try the live demo Aurora-Lens overview Get in touch