Skip to main content

IronClaw Architecture and Runtime

1. The workspace shape​

The README makes it clear that IronClaw's current story includes a dedicated Reborn runtime with its own binary and state root.

That already tells you something important:

the project is treating runtime boundaries and state layout as first-class design concerns

2. The runtime mental model​

At runtime, IronClaw generally works like this:

  1. the CLI resolves the active home and profile,
  2. configuration selects a model route,
  3. environment variables provide secrets,
  4. the runtime executes in the chosen policy and storage mode,
  5. outputs return through CLI surfaces like run, repl, or serve.

3. Why the config home matters​

Because IronClaw is explicit about its config root, files, and seed behavior, the home directory is not a side detail. It is the operating boundary for:

  • config.toml,
  • providers.json,
  • profiles,
  • and runtime state.

That makes the architecture easier to reason about than systems that hide state across many locations.

4. Policy and deployment modes are part of the architecture​

The README shows that policy and storage are not just optional features. They shape real deployment modes, including production-style configurations with PostgreSQL and explicit policy sections.

That is why IronClaw feels more like an operator-friendly runtime than a hobby CLI.

5. What to read first in code​

Start with:

  1. the Reborn quick start in the README,
  2. config and provider docs,
  3. runtime and storage code,
  4. policy surfaces,
  5. skills or automation extensions after the core flow is clear.