mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-02 23:56:24 +08:00
4104e87b65
* fix(secrets): prefer keychain over env, TOCTOU-safe generate, testable resolve Follow-up to PR #2648 addressing the four items raised in its review: 1. **Probe order swap** — `SecretsConfig::resolve()` now probes the OS keychain first, then `SECRETS_MASTER_KEY` env var, then auto-generate. Keychain storage is OS-encrypted and the stronger substrate; env var remains the CI/Docker escape hatch when no keychain exists. When both are present with different keys, keychain wins. 2. **TOCTOU safety** — before writing a newly-generated key to `.env`, re-read the file to detect a concurrent writer's key. If present, use it instead of overwriting. Closes the common-case P1-wrote-while- P2-mid-generate race; a residual microsecond window remains between the re-check and the write (a full fix would need a file lock). 3. **Zeroization analysis** — intermediate hex `String`s flow through `SecretString` but aren't zeroized. Documented that this is acceptable because the durable leak surface is `~/.ironclaw/.env` in plaintext, not heap fragments. 4. **Dead branch** — removed the unreachable `KeySource::None` arm in `auto_setup_security`'s message match (replaced with `unreachable!()`), and added a test that asserts keychain wins when both sources are present. Refactor: `resolve_inner` now takes an injected keychain probe result and an `allow_keychain_persist` flag so tests drive every branch deterministically without touching the real OS keychain (previously hung on macOS dev machines waiting for Keychain Access dialogs). Also adds `crate::config::clear_injected_var` (test-only) so tests that exercise the `inject_single_var` path can clean up the overlay and avoid cross-test contamination. Tests: - `keychain_wins_over_env_when_both_present` — probe-order invariant - `env_var_wins_when_keychain_empty` — CI fallback still works - `resolve_persists_generated_key_when_nothing_available` — regression test for #1820, now deterministic - `toctou_picks_up_concurrent_writer` — new TOCTOU regression - `short_env_key_is_rejected` — AES-256 length invariant - `read_secrets_master_key_*` — helper unit tests All run in parallel without mutex contention. * fix(secrets): revert probe-order flip; fail loudly on stale DB with fresh key Addresses PR #2653 review feedback. - Revert the probe-order change: env-first, keychain-second, auto-generate third. The previous flip diverged from every other master-key reader (SetupWizard::step_security, SetupWizard::init_secrets_context, crate::secrets::resolve_master_key, cli import), creating a correctness hazard where onboarding could encrypt a row with one key and a later startup read it with another. Also restores "explicit env var wins" and avoids the unnecessary macOS Keychain Access dialog that an eager probe triggered even when SECRETS_MASTER_KEY was set. - Make the keychain probe lazy in resolve_with_env_path: only call keychain::get_master_key() when SECRETS_MASTER_KEY is unset. - Fix read_secrets_master_key TOCTOU parser: `split_once('=')?` bailed out of the whole scan on the first non-KEY=VALUE line (blank lines, comments), defeating the re-check on any real .env. Now continues past non-assignment lines. Raised by gemini-code-assist, Copilot, and @serrrfirat (3 dupes). - New safety gate: if resolve falls through to auto_generate_and_persist, mark SecretsConfig.generated = true. AppBuilder::init_secrets now calls SecretsStore::any_exist() and errors out when a fresh key meets a populated secrets table — those rows were encrypted with a different key and silently continuing would shadow unrecoverable data. Default trait impl returns false; Postgres, libSQL, and in-memory backends override with real probes. Tests: - env_wins_over_keychain_when_both_present (replaces keychain-wins) - keychain_wins_when_env_unset (new keychain-fallback coverage) - generated_flag_tracks_auto_generate_path (flag-propagation invariant) - read_secrets_master_key_skips_blank_and_comment_lines (TOCTOU regression) - any_exist_reflects_global_store_state (safety-gate backing query) * fix(secrets): address safety-gate review findings - TOCTOU-reuse branch now returns `generated = false`. When P2's `auto_generate_and_persist` picks up the key P1 concurrently wrote to `.env`, P2's key matches whatever rows P1 has encrypted — treating it as a fresh generate would cause `init_secrets` to spuriously abort the moment P1 wrote its first row. - Extract the safety gate into `crate::secrets::verify_generated_key_safe` with a dedicated `GeneratedKeySafetyError` (two variants: `StoreAlreadyPopulated`, `ProbeFailed`). `init_secrets` now calls it and `?`-propagates. Fail-closed on probe error: the previous warn-and-continue defeated the purpose of the gate when the DB was transiently broken. - `RecordingSecretsStore` mock now delegates `any_exist` to its inner store, matching its delegation pattern for every other method. - Refresh `auto_generate_and_persist` doc comment — keychain-first is conditional on `allow_keychain_persist`. Tests: - `toctou_picks_up_concurrent_writer` now asserts `!cfg.generated`. - `generated_flag_tracks_auto_generate_path` defensively clears the injected-var overlay between branches so leaked state from a prior test can't flip the branch under test. - New `verify_generated_key_safe_*` tests cover: non-generated key + populated store (must pass), generated key + empty store (first- install happy path), generated key + populated store (must fail with `StoreAlreadyPopulated` and mention the remediation env var), probe error (must fail-closed with `ProbeFailed`; `generated = false` must short-circuit before touching the probe). * fix(secrets): roll back persistence when safety gate rejects fresh key Addresses Copilot review finding on PR #2653. `auto_generate_and_persist` writes the fresh key to keychain or `~/.ironclaw/.env` *before* `init_secrets` runs the safety gate. Without rollback, a failed gate left the key persisted, so the next restart would read it back as `source = Env/Keychain, generated = false`, skip the gate, and silently accept a key that cannot decrypt the existing rows — exactly the data-shadowing the gate exists to prevent. `crate::secrets::rollback_generated_key_persistence(source, env_path)` now undoes the persistence on gate failure (best-effort; failures are logged and swallowed since the gate's abort is the primary user signal). Supporting `bootstrap::remove_bootstrap_var_to(path, key)` strips a single line from `.env` while preserving the rest. `init_secrets` wires both together: on gate failure, roll back when `generated = true`, then propagate the original gate error. Tests: - `rollback_removes_generated_env_key` — `.env` path, preserves siblings. - `rollback_tolerates_missing_env_file` — idempotent (gate re-fires). - `rollback_with_source_none_is_a_noop` — defensive against the never- actually-produced `generated=true + source=None` pair.
IronClaw
Your secure personal AI assistant, always on your side
English | 简体中文 | Русский | 日本語 | 한국어
Philosophy • Features • Installation • Configuration • Security • Architecture
Philosophy
IronClaw is built on a simple principle: your AI assistant should work for you, not against you.
In a world where AI systems are increasingly opaque about data handling and aligned with corporate interests, IronClaw takes a different approach:
- Your data stays yours - All information is stored locally, encrypted, and never leaves your control
- Transparency by design - Open source, auditable, no hidden telemetry or data harvesting
- Self-expanding capabilities - Build new tools on the fly without waiting for vendor updates
- Defense in depth - Multiple security layers protect against prompt injection and data exfiltration
IronClaw is the AI assistant you can actually trust with your personal and professional life.
Features
Security First
- WASM Sandbox - Untrusted tools run in isolated WebAssembly containers with capability-based permissions
- Credential Protection - Secrets are never exposed to tools; injected at the host boundary with leak detection
- Prompt Injection Defense - Pattern detection, content sanitization, and policy enforcement
- Endpoint Allowlisting - HTTP requests only to explicitly approved hosts and paths
Always Available
- Multi-channel - REPL, HTTP webhooks, WASM channels (Telegram, Slack), and web gateway
- Docker Sandbox - Isolated container execution with per-job tokens and orchestrator/worker pattern
- Web Gateway - Browser UI with real-time SSE/WebSocket streaming
- Routines - Cron schedules, event triggers, webhook handlers for background automation
- Heartbeat System - Proactive background execution for monitoring and maintenance tasks
- Parallel Jobs - Handle multiple requests concurrently with isolated contexts
- Self-repair - Automatic detection and recovery of stuck operations
Self-Expanding
- Dynamic Tool Building - Describe what you need, and IronClaw builds it as a WASM tool
- MCP Protocol - Connect to Model Context Protocol servers for additional capabilities
- Plugin Architecture - Drop in new WASM tools and channels without restarting
Persistent Memory
- Hybrid Search - Full-text + vector search using Reciprocal Rank Fusion
- Workspace Filesystem - Flexible path-based storage for notes, logs, and context
- Identity Files - Maintain consistent personality and preferences across sessions
Installation
Prerequisites
- Rust 1.85+
- PostgreSQL 15+ with pgvector extension
- NEAR AI account (authentication handled via setup wizard)
Download or Build
Visit Releases page to see the latest updates.
Install via Windows Installer (Windows)
Download the Windows Installer and run it.
Install via powershell script (Windows)
irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex
Install via shell script (macOS, Linux, Windows/WSL)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh
Install via Homebrew (macOS/Linux)
brew install ironclaw
Compile the source code (Cargo on Windows, Linux, macOS)
Install it with cargo, just make sure you have Rust installed on your computer.
# Clone the repository
git clone https://github.com/nearai/ironclaw.git
cd ironclaw
# Build
cargo build --release
# Run tests
cargo test
For full release (after modifying channel sources), run ./scripts/build-all.sh to rebuild channels first.
Database Setup
# Create database
createdb ironclaw
# Enable pgvector
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
Configuration
Run the setup wizard to configure IronClaw:
ironclaw onboard
The wizard handles database connection, NEAR AI authentication (via browser OAuth),
and secrets encryption (using your system keychain). Settings are persisted in the
connected database; bootstrap variables (e.g. DATABASE_URL, LLM_BACKEND) are
written to ~/.ironclaw/.env so they are available before the database connects.
Alternative LLM Providers
IronClaw defaults to NEAR AI but supports many LLM providers out of the box. Built-in providers include Anthropic, OpenAI, GitHub Copilot, Google Gemini, MiniMax, Mistral, and Ollama (local). OpenAI-compatible services like OpenRouter (300+ models), Together AI, Fireworks AI, and self-hosted servers (vLLM, LiteLLM) are also supported.
Select your provider in the wizard, or set environment variables directly:
# Example: MiniMax (built-in, 204K context)
LLM_BACKEND=minimax
MINIMAX_API_KEY=...
# Example: OpenAI-compatible endpoint
LLM_BACKEND=openai_compatible
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=sk-or-...
LLM_MODEL=anthropic/claude-sonnet-4
See docs/capabilities/llm-providers.md for a full provider guide.
Security
IronClaw implements defense in depth to protect your data and prevent misuse.
WASM Sandbox
All untrusted tools run in isolated WebAssembly containers:
- Capability-based permissions - Explicit opt-in for HTTP, secrets, tool invocation
- Endpoint allowlisting - HTTP requests only to approved hosts/paths
- Credential injection - Secrets injected at host boundary, never exposed to WASM code
- Leak detection - Scans requests and responses for secret exfiltration attempts
- Rate limiting - Per-tool request limits to prevent abuse
- Resource limits - Memory, CPU, and execution time constraints
WASM ──► Allowlist ──► Leak Scan ──► Credential ──► Execute ──► Leak Scan ──► WASM
Validator (request) Injector Request (response)
Prompt Injection Defense
External content passes through multiple security layers:
- Pattern-based detection of injection attempts
- Content sanitization and escaping
- Policy rules with severity levels (Block/Warn/Review/Sanitize)
- Tool output wrapping for safe LLM context injection
Data Protection
- All data stored locally in your PostgreSQL database
- Secrets encrypted with AES-256-GCM
- No telemetry, analytics, or data sharing
- Full audit log of all tool executions
Architecture
┌────────────────────────────────────────────────────────────────┐
│ Channels │
│ ┌──────┐ ┌──────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ REPL │ │ HTTP │ │WASM Channels│ │ Web Gateway │ │
│ └──┬───┘ └──┬───┘ └──────┬──────┘ │ (SSE + WS) │ │
│ │ │ │ └──────┬──────┘ │
│ └─────────┴──────────────┴────────────────┘ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ Agent Loop │ Intent routing │
│ └────┬──────────┬───┘ │
│ │ │ │
│ ┌──────────▼────┐ ┌──▼───────────────┐ │
│ │ Scheduler │ │ Routines Engine │ │
│ │(parallel jobs)│ │(cron, event, wh) │ │
│ └──────┬────────┘ └────────┬─────────┘ │
│ │ │ │
│ ┌─────────────┼────────────────────┘ │
│ │ │ │
│ ┌───▼─────┐ ┌────▼────────────────┐ │
│ │ Local │ │ Orchestrator │ │
│ │Workers │ │ ┌───────────────┐ │ │
│ │(in-proc)│ │ │ Docker Sandbox│ │ │
│ └───┬─────┘ │ │ Containers │ │ │
│ │ │ │ ┌───────────┐ │ │ │
│ │ │ │ │Worker / CC│ │ │ │
│ │ │ │ └───────────┘ │ │ │
│ │ │ └───────────────┘ │ │
│ │ └─────────┬───────────┘ │
│ └──────────────────┤ │
│ │ │
│ ┌───────────▼──────────┐ │
│ │ Tool Registry │ │
│ │ Built-in, MCP, WASM │ │
│ └──────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
Core Components
| Component | Purpose |
|---|---|
| Agent Loop | Main message handling and job coordination |
| Router | Classifies user intent (command, query, task) |
| Scheduler | Manages parallel job execution with priorities |
| Worker | Executes jobs with LLM reasoning and tool calls |
| Orchestrator | Container lifecycle, LLM proxying, per-job auth |
| Web Gateway | Browser UI with chat, memory, jobs, logs, extensions, routines |
| Routines Engine | Scheduled (cron) and reactive (event, webhook) background tasks |
| Workspace | Persistent memory with hybrid search |
| Safety Layer | Prompt injection defense and content sanitization |
Usage
# First-time setup (configures database, auth, etc.)
ironclaw onboard
# Start interactive REPL
cargo run
# With debug logging
RUST_LOG=ironclaw=debug cargo run
Development
# Format code
cargo fmt
# Lint
cargo clippy --all --benches --tests --examples --all-features
# Run tests
createdb ironclaw_test
cargo test
# Run specific test
cargo test test_name
- Channels: See docs/channels/overview.mdx for setup of Telegram, Discord, and other channels.
- Changing channel sources: Run
./channels-src/telegram/build.shbeforecargo buildso the updated WASM is bundled.
OpenClaw Heritage
IronClaw is a Rust reimplementation inspired by OpenClaw. See FEATURE_PARITY.md for the complete tracking matrix.
Key differences:
- Rust vs TypeScript - Native performance, memory safety, single binary
- WASM sandbox vs Docker - Lightweight, capability-based security
- PostgreSQL vs SQLite - Production-ready persistence
- Security-first design - Multiple defense layers, credential protection
License
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT License (LICENSE-MIT)
at your option.