Iron Cage - AI Control Panel

Most AI frameworks assume R&D. We assume production in regulated industries.

     
   

---

Table of Contents

• Overview
• Architecture at a Glance
• Workspace Organization
• Documentation
• Installation & Usage
  • For Python Developers (Using Iron SDK)
  • For Control Panel Admins
  • For Platform Contributors
• Status
• License

Overview

Iron Runtime provides the core runtime modules for AI agent management including safety controls, cost tracking, reliability patterns, and the Control Panel web application.

Architecture at a Glance

This diagram shows Iron Cage's three-boundary architecture at the highest level, designed for architecture reviews and technical stakeholders.

Video Demonstarion

Visual Guide:

• Left (Developer Zone): Agent, iron_sdk, Runtime (Safety/Cost/Audit), and Gateway ALL run 100% locally
• Middle (Your Cloud - Management Plane): Control Panel for setup and management - NOT IN DATA PATH
• Right (Provider Zone): LLM provider receives only prompts with IP Token
• Critical: Request/response arrows go AROUND Control Panel (bypass architecture)

Key Points:

• Left (Developer Machine): Agent, iron_sdk, Runtime (Safety/Cost/Audit), and Gateway ALL run 100% locally. Nothing leaves your machine except prompts after local validation.
• Middle (Your Cloud): Control Panel ONLY for setup and management. NOT in request path. Handles user management, token generation, and analytics.
• Right (Third Party): LLM provider receives only prompts with IP Token. Never sees your code, data, or IC Token.

Business Value:

1. Privacy First: Agent code and data never leave developer machines (100% local execution)
2. Cost Control: Centralized budget enforcement prevents runaway AI spending
3. Security: Input/output validation protects against prompt injection, PII leaks, and credential exposure
4. Compliance: Complete audit trail for regulatory requirements and accountability
5. Flexibility: Use any LLM provider (OpenAI, Anthropic, custom) without vendor lock-in

Workspace Organization

Module Responsibilities & Boundaries (click to expand - 23 modules across 7 layers)

Entity	Responsibility	Input→Output	Scope	Out of Scope
iron_types	Shared type definitions	Raw data → Validated typed structures	Core types (AgentId, ProviderId, Budget)	Business logic, persistence
iron_cost	Cost calculation and tracking	Provider API responses → Cost metrics	Token counting, pricing, budgets	Actual API calls, rate limiting
iron_telemetry	Observability and tracing	Application events → Structured logs/metrics	Tracing, metrics, logging	Log aggregation, alerting
iron_runtime_analytics	Usage analytics and reporting	Raw usage data → Analytics reports	Aggregation, trending, forecasting	Data storage, visualization
iron_runtime_state	Runtime state management	State transitions → Persisted state	Agent state, session state	Long-term persistence, caching
iron_test_db	Test database infrastructure	Test requirements → Isolated DB instances	SQLite test instances, fixtures	Production databases, migrations
iron_safety	Content safety and moderation	User input → Safety verdicts	Content filtering, policy enforcement	Policy definition, training
iron_reliability	Resilience patterns	Unreliable operations → Reliable execution	Circuit breakers, retries, timeouts	Actual service implementations
iron_secrets	Secrets management	Plaintext secrets → Encrypted storage	Encryption, key management, access control	Secret generation, rotation policies
iron_token_manager	API token management	Provider keys → Managed tokens	Token lifecycle, usage tracking, limits	Token generation, provider integration
iron_control_api	HTTP API for control plane	HTTP requests → JSON responses	REST endpoints, auth, validation	CLI implementations, SDK
iron_llm_core	Shared LLM routing library	Provider requests → Translated API calls	Provider detection, format translation, request forwarding, cost extraction	Agent orchestration, token management
iron_runtime	Agent runtime and LLM routing	Agent requests → Provider API calls	Request translation, response parsing	Actual LLM provider SDKs
iron_cli	Command-line interface	User commands → API operations	CLI parsing, formatting, output	API implementation, business logic
iron_server_proxy	Centralized LLM proxy service	IC Token-authenticated requests → Provider API calls	Remote agent auth, key resolution, decryption, request forwarding	Agent orchestration, provider key management
iron_control_schema	Database schema definitions	Schema changes → SQL migrations	Table definitions, migrations, indexes	Query logic, application code
providers_api_tests	Integration tests for providers HTTP API	Test scenarios → pass/fail assertions	RBAC enforcement, input validation, happy paths, ownership isolation	Unit tests, load testing
providers_multi_key_tests	Integration tests for multi-key provider support	Test scenarios → pass/fail assertions	Multi-key creation, cross-tenant isolation, quota limits, handshake key routing, TOCTOU re-checks	Unit tests, load testing

Layer Organization

Foundation:     iron_types, iron_cost, iron_telemetry, iron_runtime_analytics
Infrastructure: iron_runtime_state
Feature:        iron_safety, iron_reliability, iron_secrets, iron_token_manager
Specialized:    iron_control_schema
Integration:    iron_control_api, iron_runtime, iron_llm_core
Application:    iron_cli, iron_cli_py, iron_sdk, iron_testing, iron_server_proxy
Frontend:       iron_dashboard
Tests:          providers_api_tests, providers_multi_key_tests

Documentation

Governance Compliance: ✅ Complete

Collections:

• Architecture - Execution models, layers, boundaries, data flow, integration, budget control protocol
• Protocol - REST API, WebSocket, MCP integration, budget control, token management, authentication, user management
• Security - Threat model, isolation, credential flow, audit
• Capabilities - Runtime, LLM control, sandbox, safety, credentials, MCP, observability, data
• Integration - LLM providers, secrets, identity, observability
• Deployment - Packages, actors, distribution, scaling
• Technology - Rust, PyO3, infrastructure, dependencies
• Features - CLI architecture, token management, user management
• Principles - Design, quality, errors, testing, workflow
• Constraints - Technical, business, scope, trade-offs
• Decisions - ADRs (Architecture Decision Records)

Quick Links:

• Getting Started - Choose your path: Python Developer, Control Panel Admin, or Platform Contributor
• contributing.md - Contributor workflow guide

Key Documentation:

• Budget Control Protocol - Two-token system (IC Token, IP Token), budget borrowing, incremental allocation
• Execution Models - Client-Side, Server-Side, Control Panel-Managed
• Data Flow - 11-step request flow with token translation
• Protocol Collection - Communication protocols
• Vocabulary - Canonical terminology

Complete Index: docs/readme.md - All documentation organized by category

Installation & Usage

For Python Developers (Using Iron SDK)

Tip

99% of users - you just want to protect your AI agents

Prerequisites:

• Python 3.9+ (python --version)

pip install iron-sdk

That's it! No Rust compiler, no cargo, no building required.

Quick Start:

from iron_sdk import protect_agent, BudgetConfig

@protect_agent(budget=BudgetConfig(max_usd=50.0))
def my_agent(prompt: str) -> str:
    return llm.chat(prompt)

Next Steps:

• Getting Started Guide - Complete walkthrough for all users
• SDK Documentation - Full API reference
• Examples - Runnable code examples

For Control Panel Admins

Important

Deploying the Control Panel service for your team

# Clone repository
git clone https://github.com/iron-cage/iron_runtime.git
cd iron_runtime/dev

# Configure secrets
cp .env.example .env
# Generate and add: POSTGRES_PASSWORD, JWT_SECRET, IRON_SECRETS_MASTER_KEY
# (See .env.example for generation commands)

# Deploy with Docker Compose
docker compose up -d

# Access dashboard
# http://localhost:8080

Next Steps:

• Getting Started Guide § Deploy Control Panel - Complete walkthrough
• Deployment Guide - Production deployment and troubleshooting
• Docker Compose Architecture - Design details

For Platform Contributors

Building from source (click to expand - only needed for contributing to Iron Cage itself)

# Build all Rust modules
cargo build --release

# Run tests
cargo nextest run --all-features

# Build Control Panel UI
cd module/iron_dashboard
npm install
npm run build

# Setup Python modules for development
cd module/iron_sdk
uv sync  # Installs dependencies and creates .venv

See contributing.md for contributor workflow.

Status

• Version: 0.3.0
• Status: Active development
• License: MIT