Iron Cage - AI Control Panel

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

Overview
Architecture at a Glance
Workspace Organization
Documentation
Installation & Usage
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

Iron Cage Architecture - Three-Boundary Model

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:

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

Workspace Organization

<details> <summary>Module Responsibilities & Boundaries (click to expand - 19 modules across 7 layers)</summary>

| 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_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_control_schema | Database schema definitions | Schema changes → SQL migrations | Table definitions, migrations, indexes | Query logic, application code |

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
Application:    iron_cli, iron_cli_py, iron_sdk, iron_testing
Frontend:       iron_dashboard

</details>

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

<details> <summary>Building from source (click to expand -

SDK

Install / Use

README