IronClaw

Your secure personal AI assistant, always on your side

English | 简体中文 | Русский | 日本語 | 한국어

Reborn Quick Start • Philosophy • Features • Installation • Configuration • Security • Architecture

---

IronClaw Reborn Quick Start

IronClaw Reborn is the standalone runtime on the reborn-integration branch. It uses the separate ironclaw-reborn binary from the ironclaw_reborn_cli package and a separate Reborn state root. It does not use the legacy ironclaw state directory as its config root.

For the older ironclaw binary, see Installation and Legacy IronClaw Usage.

Build or run the binary

From the repo root:

cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- --help

Or build it first:

cargo build -p ironclaw_reborn_cli --bin ironclaw-reborn
./target/debug/ironclaw-reborn --help

The default Reborn home is $HOME/.ironclaw/reborn. Override it with an absolute path when you want isolated state:

export IRONCLAW_REBORN_HOME="$PWD/.reborn-home"
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- config path

config path and doctor are safe diagnostics; they report the resolved home, profile, config.toml, providers.json, and v1_state: not-used. They do not create Reborn state or seed config files.

Configure the model route

The CLI-native way to configure Reborn's default model route is:

export IRONCLAW_REBORN_HOME="$PWD/.reborn-home"
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- models set-provider openai --model gpt-5-mini

That writes $IRONCLAW_REBORN_HOME/config.toml with [llm.default] and the provider's credential env-var name. Check it with:

cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- models status
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- models list openai

For OpenAI, set the secret value in the environment before starting:

export OPENAI_API_KEY="sk-..."
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- run --message "hello"

Omit --message or use repl for an interactive stdin session:

cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- repl

config.toml shape

config init creates editable starter files:

cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- config init

It writes:

• $IRONCLAW_REBORN_HOME/config.toml
• $IRONCLAW_REBORN_HOME/providers.json

A minimal configured model route looks like:

[llm.default]
provider_id = "openai"
model = "gpt-5-mini"
api_key_env = "OPENAI_API_KEY"

config.toml may also include optional sections such as [boot], [identity], [runner], and [skills]; config init writes commented guidance for the supported fields.

If config.toml is missing, the first stateful runtime start through run, repl, or serve seeds a sparse file with api_version and the safe local-dev boot profile. Read-only commands and run --dry-run stay side-effect-free. One-off environment selections such as IRONCLAW_REBORN_PROFILE=local-dev-yolo are not persisted into the seeded file.

Important: api_key_env is the name of an environment variable, not the secret itself. Reborn rejects inline secret-shaped values in config.toml and providers.json.

Production storage uses the same env-only pattern. A production Reborn config may name the PostgreSQL URL variable, but must not contain the raw URL:

[storage]
backend = "postgres"
url_env = "IRONCLAW_REBORN_POSTGRES_URL"
secret_master_key_env = "IRONCLAW_REBORN_SECRET_MASTER_KEY"
# Optional; defaults to 2. Keep below the PostgreSQL server or managed
# session-pool cap after reserving capacity for restarts and operator sessions.
pool_max_size = 2

[policy]
deployment_mode = "hosted_multi_tenant"
default_profile = "secure_default"

Set IRONCLAW_REBORN_POSTGRES_URL in the process environment, and set IRONCLAW_REBORN_SECRET_MASTER_KEY to independent cryptographic key material. Managed remote PostgreSQL providers must use TLS, for example by appending sslmode=require. Production run also requires an explicit [policy] section. The first production launch slice supports runtime policies that do not require a tenant-sandbox process binding.

Once [llm.default] exists, that config selects the provider. LLM_BACKEND is only an env fallback when no default LLM slot is configured. To switch providers after writing config, use models set-provider <provider> or edit [llm.default].provider_id.

Env-only model selection

If $IRONCLAW_REBORN_HOME/config.toml is absent or has no [llm.default], Reborn can resolve the LLM from environment variables. A sparse first-run seeded config does not include [llm.default], so env-only model selection continues to work:

export IRONCLAW_REBORN_HOME="$PWD/.reborn-env-only"
export LLM_BACKEND=openai
export OPENAI_API_KEY="sk-..."
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- run --message "hello"

Common provider env vars:

Provider	Selector	Required env
OpenAI	LLM_BACKEND=openai	OPENAI_API_KEY; optional OPENAI_MODEL, OPENAI_BASE_URL
Anthropic	LLM_BACKEND=anthropic	ANTHROPIC_API_KEY; optional ANTHROPIC_MODEL, ANTHROPIC_BASE_URL
OpenAI-compatible	LLM_BACKEND=openai_compatible	LLM_BASE_URL; optional LLM_API_KEY, LLM_MODEL
OpenRouter	LLM_BACKEND=openrouter	OPENROUTER_API_KEY; optional OPENROUTER_MODEL
Ollama	LLM_BACKEND=ollama	no key; optional OLLAMA_BASE_URL, OLLAMA_MODEL
Codex auth	LLM_BACKEND=openai_codex	LLM_USE_CODEX_AUTH=true or CODEX_AUTH_PATH; optional OPENAI_CODEX_MODEL

Use models list <provider> to see the exact provider metadata compiled into the current branch.

Startup variables