Copyright © 2026 Saccadic LLC · Patent pending.

Browse chapters
  1. Release NotesChanges by version
  2. Chapter 1What IRIS Is and Is Not
  3. Chapter 2The IRIS Data Model
  4. Chapter 3How IRIS Measures
  5. Chapter 4Safe Interpretation and the First 15 Minutes
  6. Chapter 5Dashboard Overview
  7. Chapter 6Installation
  8. Chapter 7Configuration
  9. Chapter 8Build the Model Spec and Probe Set
  10. Chapter 9Minimal Tracker Integration
  11. Chapter 10Launch the Bench and Verify Capture
  12. Chapter 11Runtime Control, Signals, Metrics, and Logs
  13. Chapter 12Integration Patterns by Model Family
  14. Chapter 13Distributed Training
  15. Chapter 14Artifacts, Reports, Export, and Security
  16. Chapter 15Troubleshooting
  17. Chapter 16Whole Model and Layer Structure
  18. Chapter 17Domain Training and Affinity
  19. Chapter 18Attention-Head Diagnostics
  20. Chapter 19MoE Expert and Router Diagnostics
  21. Chapter 20Facets and Emergent Pathways
  22. Chapter 21Gradient Residuals, Stability, Curvature, and Update Efficiency
  23. Chapter 22Adaptive Cadence and Event Detection
  24. Chapter 23CLI Reference
  25. Chapter 24Configuration-Key Reference
  26. Chapter 25API Reference
  27. Chapter 26File and Schema Reference
  28. Chapter 27Glossary and Concept Index
  29. Chapter 28The Flow Map
  30. Appendix ADiagnostic Availability Matrix
  31. Appendix BLLM Prompt Library
On this page

Chapter 7 — Configuration

Configuring IRIS™ (~/.iris/)

IRIS keeps hand-editable TOML settings under ~/.iris/. A missing file uses defaults; you do not need to create all files before starting. Keep credential-bearing configuration private and out of source control.

File Purpose
iris-bench.cfg Bench launch preferences, port, log settings, and remembered folder-tree selections.
iris-tracker.cfg Host-wide tracker preferences. Per-run live commands use the run's iris.cmd file.
iris-butler.cfg Butler defaults; a run's iris.cfg can override its global settings.
derived_metrics.toml Saved expressions for the User tab's Derived section.
config.toml Settings shared by the tools, including a license-server override for a private/staging deployment.

Example Bench preference:

[server]
port = 8765

Precedence: which source wins

The normal precedence is built-in defaults, then the tool's configuration file, then supported environment overrides, then CLI flags or constructor arguments. Later settings override earlier ones. The exact supported keys are version-specific; do not add a key just because a different program uses it.

The Bench's --no-open flag can suppress automatic browser opening; it does not reverse an open_browser = false preference back to true. The tracker's debug=True similarly forces verbosity upward; debug=False does not override a more verbose environment or file preference.

A malformed file is different from a missing file. Tracker configuration errors can prevent startup rather than silently using defaults. Read the named file and error, correct the value or remove the unintended setting, and retry. See Chapter 24 for reference.

Browse and switch runs

In IRIS bundles & benches, the triangle opens a folder; the folder icon selects which runs appear in the list. Opening and selecting are separate. Switch here changes the run shown in the existing Bench, while Start opens a separate Bench for the selected run. The folder tree remembers its state, so you normally do not need to hand-edit its keys.

Network access is a separate responsibility

The Bench has no password. Anyone who can reach its port can view it. Changing anything, including tracker commands, notes, restarting, or switching runs, requires localhost on the Bench machine or a supported SSH port-forward as your own login account. See Chapter 10 for the connection requirements. Network policy controls viewing access. Use a trusted, encrypted path for remote viewing; see Chapter 14.