Rune — Architecture Overview¶

Rune is a production-grade AI agent runtime written in Rust. It handles the full lifecycle of AI agents: packaging, deploying, scheduling, executing, and networking them — across Docker, Kubernetes, and WASM backends.

High-Level Overview¶

flowchart TB
    subgraph cli [CLI]
        RuneCmd[rune-cmd]
    end

    subgraph gateway [Gateway]
        RuneGateway[rune-gateway]
    end

    subgraph services [Services]
        RuneCp[rune-cp]
        RuneRuntime[rune-runtime]
        RuneChannels[rune-channels]
    end

    subgraph storage [Storage]
        RuneStorage[rune-storage]
    end

    subgraph backends [Backends]
        Docker[Docker]
        K8s[Kubernetes]
        WASM[WASM]
    end

    RuneCmd -->|HTTP/local| RuneGateway
    RuneGateway --> RuneCp
    RuneGateway --> RuneRuntime
    RuneGateway --> RuneChannels
    RuneCp --> RuneStorage
    RuneRuntime --> RuneStorage
    RuneRuntime --> Docker
    RuneRuntime --> K8s
    RuneRuntime --> WASM

Component roles:

• rune-cmd — CLI: agent ls/inspect/sessions/stop/rm, run, daemon start/stop/status, compose up/down/ps, cluster, debug
• rune-gateway — REST API, A2A JSON-RPC, channels webhook, rate-limit, JWT auth, Prometheus /metrics
• rune-cp — Control plane: deployment admission, registry, rollout
• rune-runtime — Execution engine: planner, tool dispatch, session management
• rune-channels — Messaging adapters (Slack, Telegram, etc.)
• rune-storage — SQLite + Raft consensus + object store

Crate Map¶

Agent Package Layout¶

An agent is a directory with a Runefile and optional extras:

my-agent/
├── Runefile        # required — identity, runtime config, model config
├── workflow.yaml   # optional — DAG of agent steps
└── tools/
    ├── search.yaml     # tool descriptor
    └── search.py       # or .js, .wasm, Dockerfile

rune-spec::AgentPackage::load() reads the Runefile and auto-injects built-in rune@* tool descriptors for any tool names starting with rune@.

Storage Layer (rune-storage)¶

RuneStore is the single storage abstraction used everywhere.

Two Modes¶

Standalone — All reads and writes go directly to a local SQLite database. Default for single-node deployments.

Cluster — Writes are proposed through OpenRaft consensus and applied to every node's SQLite once committed. Reads go directly to local SQLite (eventually consistent within Raft commit latency).

What's Stored¶

• Deployments — desired replica count, active/inactive state
• Replicas — backend instance ID, state (pending/ready/draining/failed), load counter, heartbeat timestamp
• Sessions — message history, checkpoint, assigned replica
• Requests — input payload, output, status
• Tool invocations — per-tool audit trail
• Agent calls — A2A call graph (caller, callee, depth, latency)
• A2A tasks — task state machine (working/completed/cancelled/failed)
• Cache — session-to-replica routing with TTL, rate-limit counters
• Registry — registered agent versions with OCI image reference
• Network — per-agent network memberships and direct replica endpoints
• Schedules — cron-based and interval-based schedule records
• Policy audit — allowed/denied policy decisions

Execution Engine (rune-runtime)¶

Request Lifecycle¶

1. Gateway receives POST /v1/agents/:name/invoke
2. ReplicaRouter resolves deployment → picks least-loaded healthy replica
3. SessionManager creates or restores a session (message history from SQLite)
4. Planner runs the LLM loop:
5. Sends messages to the LLM (Anthropic, OpenAI, Gemini, Copilot, or ClaudeCode)
6. Receives streamed ContentBlocks
7. When the model calls a tool → ToolDispatcher runs it
8. Appends assistant + tool result messages to session
9. Repeats until stop or max_steps reached
10. Result is streamed back via SSE or returned as JSON

Components¶

Gateway Middleware Stack¶

(outermost → innermost)

1. TraceLayer — OpenTelemetry distributed tracing
2. auth — JWT validation (via jsonwebtoken)
3. rate_limit — token-bucket rate limiter

Observability¶

• Structured logging — tracing + tracing-subscriber (JSON or pretty format, RUST_LOG env filter)
• Distributed tracing — OpenTelemetry OTLP export via gRPC (OTEL_ENDPOINT env var)
• Metrics — metrics + metrics-exporter-prometheus, exposed at GET /metrics
• Audit log — every policy decision is written to rune-storage with kind, resource, allowed/denied, reason, and request ID

Deployment Modes¶