<p align="center"> <img src="ironclaw.png" alt="IronClaw" width="200"/> </p> <h1 align="center">IronClaw</h1> <p align="center"> <strong>Your secure personal AI assistant, always on your side</strong> </p> <p align="center"> <a href="#philosophy">Philosophy</a> • <a href="#features">Features</a> • <a href="#installation">Installation</a> • <a href="#configuration">Configuration</a> • <a href="#security">Security</a> • <a href="#architecture">Architecture</a> </p>

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.

<details> <summary>Install via Windows Installer (Windows)</summary>

Download the Windows Installer and run it.

</details> <details> <summary>Install via powershell script (Windows)</summary>

irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex

</details> <details> <summary>Install via shell script (macOS, Linux, Windows/WSL)</summary>

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh

</details> <details> <summary>Compile the source code (Cargo on Windows, Linux, macOS)</summary>

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.

</details>

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). All settings are saved to ~/.ironclaw/settings.toml.

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

Telegram channel: See docs/TELEGRAM_SETUP.md for setup and DM pairing.
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.

ironclaw (nearai)

Implemented Skills

README