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.92+
• PostgreSQL 15+ with pgvector extension
• NEAR AI account (authentication handled via setup wizard)
• libclang and a working C toolchain if you build the WeChat voice/SILK path from source

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

Develop in the VS Code Dev Container (recommended on Windows)

If Windows security blocks fresh Rust binaries or access to .cargo / .rustup, open this repository with the Dev Containers extension and Docker Desktop instead of using host cargo.

The repo ships with a .devcontainer/ configuration, so cargo, rustc, terminals, and rust-analyzer run inside Linux. In VS Code, run Dev Containers: Reopen in Container from the Command Palette.

The container's post-create step pins the workspace to Rust 1.92 and attempts to install the wasm32-wasip2 target plus wasm-tools. If your network is slow during first setup, rerun .devcontainer/post-create.sh inside the container.

Develop in a normal local VS Code window on Windows

If you want to keep the repository open locally in VS Code instead of reopening it in a container, the workspace now ships with a Windows-safe Rust bootstrap.

Run the task Rust: Bootstrap local Windows toolchain once. It installs Rust into .ironclaw-dev/windows-rust/ inside the repo instead of using %USERPROFILE%\\.cargo and %USERPROFILE%\\.rustup, then pins the toolchain from rust-toolchain.toml.

After that, local VS Code terminals, workspace cargo tasks, rust-analyzer diagnostics, and formatting use the repo-local Rust home. The default build task is Cargo: Check (local Windows-safe).

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.

Optional: WeChat voice notes (audio/silk) require the standalone ironclaw-silk-decoder helper to be transcribable. It's excluded from the default workspace build because silk-codec pulls in bindgen/libclang. Build it separately with ./crates/ironclaw_silk_decoder/build.sh (needs libclang + a C toolchain) and put the resulting binary on $PATH, beside the ironclaw binary, or pointed at by IRONCLAW_SILK_DECODER. Without it, voice messages are still delivered — just as raw audio/silk blobs.

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.

OpenSpace as an MCP Co-Worker

If openspace-mcp is installed on your PATH, IronClaw can use OpenSpace as an MCP-backed delegated execution surface.

Recommended first setup: use stdio transport and register OpenSpace through IronClaw's own MCP CLI.

ironclaw mcp add openspace --transport stdio --command openspace-mcp --description "OpenSpace delegated execution and skill search" --env OPENSPACE_WORKSPACE=/path/to/OpenSpace

Optional environment variables:

• OPENSPACE_API_KEY — enables OpenSpace cloud skill search and uploads
• OPENSPACE_HOST_SKILL_DIRS — optional host skill directories for OpenSpace to index in addition to its own local skills

Validate the connection:

ironclaw mcp test openspace

If you also want current third-party library and SDK docs inside the same host, register Context7 as a second stdio MCP server:

ironclaw mcp add context7 --transport stdio --command npx --arg=-y --arg=@upstash/context7-mcp --description "Current third-party library and SDK docs via Context7"
ironclaw mcp test context7

If you also want broader live web search and page fetch inside the same host, register Exa as another stdio MCP server:

ironclaw mcp add exa --transport stdio --command npx --arg=-y --arg=exa-mcp-server --description "Exa web search and page fetch"
ironclaw mcp test exa

If npx is not on your PATH, point --command at your local npx or npx.cmd binary instead.

If you need authenticated Exa access, provide EXA_API_KEY through IronClaw's local environment rather than committing it to repo files.

Once OpenSpace is registered, IronClaw can expose these OpenSpace-backed MCP tools:

• openspace_search_skills
• openspace_execute_task
• openspace_fix_skill
• openspace_upload_skill

This repository also bundles three OpenSpace-specific skills for host-side routing:

• openspace-discovery
• openspace-delegation
• openspace-phased-delegation

Recommended order for library, framework, or live web work: search the local repo first, use the bundled OpenSpace skills and tools second, reach for Context7 when the missing piece is current external API documentation, and use Exa only when broader live web search or page fetch is the missing piece.

Use stdio first. Move to HTTP transport only when you need OpenSpace running as a separate long-lived service.

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

Engine v2 is opt-in right now. If you want to run the new engine instead of the legacy agent loop, start IronClaw with ENGINE_V2=true. See Engine v2 architecture for more details.

# First-time setup (configures database, auth, etc.)
ironclaw onboard

# Start interactive REPL
cargo run

# Start interactive REPL with engine v2
ENGINE_V2=true cargo run

# Engine v2 with debug logging
ENGINE_V2=true 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.sh before cargo build so 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.