Installation guide

Before you start #

Bring it up #

The four secrets #

All four are required and none has a default. Compose refuses to start without them, which is deliberate: an admin surface that boots unauthenticated by accident is worse than one that does not boot.

export TF_KEY=<your Token Factory key>
export IAG_ADMIN_TOKEN=$(openssl rand -hex 24)
export IAG_SIGNING_KEY=$(openssl rand -hex 32)
export IAG_UPSTREAM_BASE_URL=https://<factory-origin>

docker compose -f deploy/lite/docker-compose.yml up --build

To check the compose file without a Docker daemon at all:

TF_KEY=x IAG_ADMIN_TOKEN=x IAG_SIGNING_KEY=x \
  docker compose -f deploy/lite/docker-compose.yml config

Watching it boot #

Boot is fail-closed and says what it did. A real boot against a live Factory looks like this:

INFO config loaded            config_sha256=507885ca… audit=config.loaded
INFO migrations complete      applied="[0001_init 0002_system_prompt 0003_governed_gateway …]"
INFO upstream credential resolved   source=env key_source=env:TF_KEY
INFO upstream state transition      from_state=unknown to_state=ready origin=boot
INFO listening                addr=0.0.0.0:8080 governed_gateway=true
INFO admin listening          addr=0.0.0.0:8081 note="admin API + console"

An unset admin token, a signing key under 32 bytes, a missing upstream credential, an unreachable database or IdP each exit non-zero naming the config field, and Compose restarts the container until boot passes. The upstream probe is a zero-spend call: it classifies the Factory as ready without buying a single token.

curl -s localhost:8080/healthz     # liveness
curl -s localhost:8080/readyz      # readiness, carries the classified upstream state

First requests #

Workspace, policy, key #

Three calls against the admin listener on 8081. A workspace maps to one upstream project; a policy says what that workspace may do; a virtual key is what an application actually holds.

A="Authorization: Bearer $IAG_ADMIN_TOKEN"
B=http://127.0.0.1:8081/admin/v1

curl -s -H "$A" -X POST $B/workspaces \
  -d '{"name":"ws-pilot","tf_project_id":"proj-1"}'

curl -s -H "$A" -X PUT $B/policy/ws-pilot -d '{
  "allowed_models":["openai/gpt-oss-20b","openai/gpt-oss-120b"],
  "features":{"routing":true,"cache":true,"trim":true,"verify":true,"tool_gating":false},
  "baseline_model":"openai/gpt-oss-120b",
  "budget_posture":"fail-open"}'

KEY=$(curl -s -H "$A" -X POST $B/keys \
  -d '{"workspace":"ws-pilot","principal":"alice","name":"laptop","ttl_hours":24}' \
  | jq -r .token)

Calling the gateway #

Any OpenAI or Anthropic SDK works unchanged: point its base URL at the application listener on 8080 and give it the virtual key.

curl -si localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"model":"iag/auto","messages":[{"role":"user","content":"Say hello."}]}'

curl -s localhost:8080/v1/messages \
  -H "x-api-key: $KEY" -H 'content-type: application/json' \
  -d '{"model":"iag/fast","max_tokens":64,
       "messages":[{"role":"user","content":"Say hello."}]}'

OPENAI_BASE_URL=http://localhost:8080/v1
OPENAI_API_KEY=$KEY

Response headers #

Every response explains itself. These are computed per request, never constants.

What happened, from the admin API or the console at http://127.0.0.1:8081/:

curl -s -H "$A" "$B/requests?workspace=ws-pilot" | jq .
curl -s -H "$A" "$B/overview?workspace=ws-pilot&window=24h" | jq .

Configuration #

deploy/lite/config.yaml is the compose-profile config; the fully commented schema is iag-lite/config.example.yaml. Every secret is named by environment variable, never written in the file.

The catalog #

This is the one section you must edit. Put in the models your Factory project serves and the rates on your contract.

catalog:
  floor_rate: {input_per_1m: 15.0, output_per_1m: 60.0}
  models:
    - id: openai/gpt-oss-20b
      tier: small
      context_length: 128000
      capabilities: [chat, tool-use, json-mode]
      input_per_1m: 0.05
      output_per_1m: 0.20
      # cached_input_per_1m: 0.005   # set from your contract; unset claims no discount

Optimisers #

routing:
  aliases: {iag/auto: cascade, iag/fast: small, iag/quality: large}
  max_escalations: 1
  baseline_model: z-ai/glm-5.2     # what savings are measured against
  cache_ttl: 10m

canon:
  enabled: true                    # keep the cacheable prefix byte-stable
  volatile_fields: [timestamp, request_id, nonce, trace_id]

trim:
  retained_verbatim_turns: 6
  min_prompt_tokens: 32000         # the trimmer does not run below this

verify:
  judge: {enabled: false, model: "", max_usd_per_check: 0.002}

A local model on the small tier #

Optional, off by default. Run any OpenAI-compatible server, declare it as a catalog model, and iag/fast lands there instead of the Factory.

# on the host, not in the container
mlx_lm.server --model mlx-community/Qwen3-4B-Instruct-2507-4bit --host 0.0.0.0 --port 8090

- id: local/qwen3-4b
  tier: small
  context_length: 32000
  capabilities: [chat, tool-use, json-mode]
  input_per_1m: 0
  output_per_1m: 0
  upstream:
    base_url: "http://host.docker.internal:8090"
    model: "mlx-community/Qwen3-4B-Instruct-2507-4bit"

Nothing else changes. The model is allowed by workspace policy like any other, and the catalog shows it as local:host.docker.internal:8090 because prompt content reaches that endpoint. Zero rates are accepted here and only here: a model with its own upstream may honestly cost nothing per token, while a Factory model may not.

Going to production #

Troubleshooting #