Skip to content
Pantheon

Iris

Iris is the client-front component. It runs on the machine where agents live — typically your development workstation or laptop — and intercepts outbound Anthropic API calls before they leave the machine.

No changes to agent code are required. Iris presents a local socket at 127.0.0.1:8080 that speaks the full Anthropic Messages API. Point your ANTHROPIC_BASE_URL environment variable at it and Iris handles the rest.

What Iris does

Section titled “What Iris does”
  1. Intercepts — receives every outbound request your agents make to the Anthropic Messages API.
  2. Evaluates policy — checks the model name and any per-teammate tags against your routing table.
  3. Routes — forwards to the local fleet via minotaur, or passes through to api.anthropic.com, or both in fallback mode.
  4. Logs — records every routing decision locally for inspection with pantheon iris log.

Installation

Section titled “Installation”

Iris is installed as part of the standard install flow when you select the client front role:

Terminal window
curl --proto '=https' --tlsv1.2 -fsSL https://pantheon.lhocke.dev/installs/install.sh | sh
# Select: client front

The installer configures a local socket, writes a default routing policy, and prompts for your orchestrator host’s hermes address.

Configuration

Section titled “Configuration”

The routing policy lives at ~/.config/pantheon/iris.toml:

[iris]
listen = "127.0.0.1:8080"
orchestrator = "minotaur.local:7677"   # hermes endpoint on your orchestrator host


[routing]
default = "auto"   # local | anthropic | auto


[routing.overrides]
"claude-opus-*"   = "anthropic"
"claude-sonnet-*" = "auto"
"*"               = "local"

Edit this file and run pantheon iris reload to apply changes without restarting.

CLI

Section titled “CLI”
Terminal window
pantheon iris status        # show current routing table and fleet state
pantheon iris log           # tail routing decisions (live)
pantheon iris log --tail 50 # last 50 decisions
pantheon iris reload        # reload config without restart
pantheon iris stop          # stop the local Iris socket

Environment variable

Section titled “Environment variable”

Set this in your shell profile or agent launcher so clients reach Iris:

Terminal window
export ANTHROPIC_BASE_URL="http://127.0.0.1:8080"

Claude Code, the Anthropic SDK, and most CLI tools respect ANTHROPIC_BASE_URL automatically.