mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-03 08:06:01 +08:00
7b41f0da18
* fix(docker): repair home ownership so a root-written file cannot brick boot
A hosted instance crash-looped on every restart with:
Error: could not resolve LLM environment fallback: Provider
provider_registry request failed: failed to read provider registry
overlay `/data/ironclaw-reborn/providers.json`: Permission denied (os
error 13)
while `config.toml` in the same directory loaded fine — so this was one
file's ownership, not directory traversal. The provider-registry overlay is
fail-closed by design (an unreadable explicit overlay must not silently fall
back to compiled-in defaults), so a single root-owned file ends the boot
rather than degrading it.
Root cause is the interaction between two deliberate choices. #7723 changed
the runtime image from `USER ironclaw` to `USER root`, because sshd must
start as root before the entrypoint drops via `gosu` — so for the first time
a root process can write to the persistent volume. And the root pass's
`chown` is non-recursive, because start-sshd.sh refuses to run unless it owns
`$IRONCLAW_REBORN_HOME/ssh`. Together they mean the entrypoint fixes the home
DIRECTORY and leaves its CONTENTS untouched, and a volume outlives the image
that wrote it.
Repair ownership of the home's contents in the root pass, excluding `ssh`.
Recursing into `ssh` would trade this crash loop for a broken SSH listener,
which is why the exclusion is explicit rather than incidental.
Reproduced before fixing, in debian:bookworm-slim, seeding a volume the way
the failing instance looks:
BEFORE -rw-r--r-- ironclaw ironclaw config.toml
-rw------- root root providers.json
AFTER entrypoint (root pass ran): unchanged
uid 1000 reading providers.json: Permission denied
With the fix, providers.json and nested files become ironclaw-owned and
readable, while `ssh/` and its host key stay root:root.
Regression test `home_contents_ownership` asserts both halves — that every
top-level home entry is handed to chown, and that `ssh` is NOT. It fails
without the fix and passes with it. The chown stub records argv rather than
executing, so the test pins what the root pass asks for.
Scope note: this is a robustness fix, not a diagnosis of one box. I could not
inspect the instance, so I have not proven how its providers.json became
root-owned — only that this mechanism produces exactly the logged error and
that `USER root` is what makes root-owned files possible at all. A persistent
volume shared across image versions with differing runtime users should not be
able to brick boot regardless of which write created the file.
Also applies to the 1.3 line, which has carried `USER root` since #7723.
Verified: entrypoint self-tests pass on debian:bookworm-slim as a non-root
user (as CI runs them); the real-sshd regression harness still reports 16/16
against the release/1.3.1 baseline; a full entrypoint -> start-sshd -> real
SSH login still succeeds as agent:1000 with the ssh state dir root-owned;
shellcheck clean apart from two pre-existing SC2016 notices.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(docker): follow a symlinked home and pin the repair's real properties
Review of the first cut found three defects, two of which meant the fix or its
test did not do what they claimed.
**The repair silently did nothing when the home is a symlink.** `find` defaults
to a physical walk, so `find "$IRONCLAW_REBORN_HOME" -mindepth 1` matches
nothing when the start path is a symlink -- no error, no repair, and the boot
loop persists with no diagnostic. Verified in debian:bookworm-slim:
`find /link -mindepth 1 -maxdepth 1` returns 0 entries, `find -H /link` returns
2. Now uses `-H`, which follows the start path only, so symlinks planted
*inside* the home are still never followed; combined with `chown -h`, a
planted symlink cannot redirect ownership outside the home. Confirmed: a
`planted -> /etc` symlink leaves /etc and /etc/passwd root-owned.
**The test did not pin recursion.** It asserted the top-level `nested` entry
appeared in the recorded argv, which stays true even with a non-recursive
chown -- while `nested/deep.db` would keep its old ownership and still brick
startup. It now asserts the nested file itself.
**The test swallowed the entrypoint's exit status** with `) || true`, so a
run that failed after the ownership commands could still pass on argv alone.
The run is now required to succeed.
Also dropped a `! -user ironclaw` filter added in the first cut as a
steady-state optimization. Its own tests caught why it was wrong: the
predicate resolves the name at find time and errors with
`find: 'ironclaw' is not the name of a known user` wherever it does not
resolve, which under `set -e` aborts the entire boot. That trades a rare
ownership repair for a guaranteed crash, and no review finding asked for it.
Each property is now proven discriminating by mutation:
- drop `-H` -> FAIL symlinked_home_ownership
- top-level only -> FAIL home_contents_ownership (nested/deep.db)
- stop pruning ssh -> FAIL home_contents_ownership (ssh chowned)
Verified: entrypoint self-tests pass on debian:bookworm-slim as a non-root
user; the real-sshd harness still reports 16/16 against the release/1.3.1
baseline; shellcheck clean apart from two pre-existing SC2016 notices.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
IronClaw
Your secure personal AI assistant, always on your side
English | 简体中文 | Русский | 日本語 | 한국어
Quick Start • Philosophy • Features • Installation • Configuration • Security • Architecture
Quick Start
Choose an ironclaw-v* tag from the Releases page,
then install it on macOS, Linux, or Windows/WSL. Replace X.Y.Z with the
selected version, including any prerelease suffix:
IRONCLAW_RELEASE_TAG=ironclaw-vX.Y.Z
curl --proto '=https' --tlsv1.2 -LsSf \
"https://github.com/nearai/ironclaw/releases/download/${IRONCLAW_RELEASE_TAG}/ironclaw-installer.sh" | sh
Then run the guided setup:
ironclaw onboard
Choose an LLM provider, enter its API key in the hidden prompt, and accept the default model or enter another one. IronClaw provisions its local configuration, encrypted credential store, and WebUI login token. On macOS and Linux it also installs and starts the background service, then prints a link that opens the WebUI.
Use ironclaw status to check the service and print the login link again.
Windows users can start the WebUI in the foreground with ironclaw serve.
See Installation for Windows installers and source builds.
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
The Releases page provides pre-built binaries and installers.
Install via Windows Installer (Windows)
Open the selected ironclaw-v* release, download
ironclaw-x86_64-pc-windows-msvc.msi, and run it.
Install via PowerShell script (Windows)
$IronClawReleaseTag = "ironclaw-vX.Y.Z"
irm "https://github.com/nearai/ironclaw/releases/download/$IronClawReleaseTag/ironclaw-installer.ps1" | iex
Install via shell script (macOS, Linux, Windows/WSL)
IRONCLAW_RELEASE_TAG=ironclaw-vX.Y.Z
curl --proto '=https' --tlsv1.2 -LsSf \
"https://github.com/nearai/ironclaw/releases/download/${IRONCLAW_RELEASE_TAG}/ironclaw-installer.sh" | sh
Build and install from source
Source builds require Rust 1.96+ and Node.js 22+ with Corepack/pnpm.
git clone https://github.com/nearai/ironclaw.git
cd ironclaw
corepack enable pnpm
cargo install --locked --path crates/app/ironclaw_cli
Configuration
ironclaw onboard is the primary configuration path. It writes Reborn state
under $HOME/.ironclaw/reborn by default, stores the selected LLM credential
in the encrypted local secret store, and preserves existing configuration when
it is run again.
Inspect the current setup with:
ironclaw status
ironclaw models status
ironclaw config list
To switch providers after onboarding, select the route and then store its API key using the hidden prompt:
ironclaw models set-provider openai --model gpt-5-mini
ironclaw config set openai.api_key
Additional settings use the same command. For example:
ironclaw config set google.client_id YOUR_CLIENT_ID
ironclaw config set google.client_secret
ironclaw config set google.redirect_uri YOUR_REDIRECT_URI
ironclaw config set webui.token --rotate
Secret values never accept a positional argument; IronClaw prompts for them without echoing the value. Channels such as Slack and Telegram have no configuration-file settings and no CLI enablement key: install the extension and complete its setup on the WebUI Extensions page, which is what makes the route serve.
Configuration writes never restart the service automatically. Run
ironclaw service restart after a change that affects the running service,
and use ironclaw config set --help for the complete list of supported keys.
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 IronClaw's application state
- 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
# Check the background service and print the WebUI login link
ironclaw status
# Start an interactive terminal session
ironclaw repl
# Run one turn
ironclaw run --message "hello"
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.
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.