• 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

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

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

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

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

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

# 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

# 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

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