ironclaw README

The project's README from github.com/nearai/ironclaw. As one markdown file: README.md.

IronClaw

IronClaw

Your secure personal AI assistant, always on your side

License: MIT OR Apache-2.0 Telegram: @ironclawAI Reddit: r/ironclawAI gitcgr

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:

IronClaw is the AI assistant you can actually trust with your personal and professional life.

Features

Security First

Always Available

Self-Expanding

Persistent Memory

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:

WASM ──► Allowlist ──► Leak Scan ──► Credential ──► Execute ──► Leak Scan ──► WASM
         Validator     (request)     Injector       Request     (response)

Prompt Injection Defense

External content passes through multiple security layers:

Data Protection

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

OpenClaw Heritage

IronClaw is a Rust reimplementation inspired by OpenClaw. See FEATURE_PARITY.md for the complete tracking matrix.

Key differences:

License

Licensed under either of:

at your option.

ironclaw (nearai/ironclaw)

Searching Database…

12.7K ·GitHub
Ironclaw
What is this?IronClaw is an open-source personal AI assistant — an Agent OS focused on privacy, security and extensibility, written in Rust. Its core principle: your assistant works for you, and all your data stays local and under your control.
Is this a desktop app, a CLI, or a web service?It runs as a background service on your machine with a browser WebUI for chat, memory, jobs and logs. You can also reach it from a REPL, HTTP webhooks, and Telegram or Slack channels.
How do I install it and get it talking to a model?Grab a prebuilt binary from the Releases page, then run the guided 'ironclaw onboard': pick an LLM provider, enter its API key, choose a model. On macOS and Linux it then installs and starts the background service and prints a WebUI login link ('ironclaw status' re-prints it).
Do I need an API key or any developer tooling first?Just an API key from whichever LLM provider you choose — it is entered during onboarding into an encrypted local secret store. Only building from source needs extra tooling: Rust 1.96+ and Node.js 22+ with Corepack/pnpm.
Does the Windows setup work the same as on Mac and Linux?Almost, but not quite: the auto-starting background service is installed only on macOS and Linux. On Windows, start the WebUI in the foreground with 'ironclaw serve', or use WSL for the full service setup.
Which systems can it run on?macOS, Linux and Windows/WSL, with prebuilt binaries and installers (an MSI for Windows) available on the Releases page.
Does any of my data or thesecretsever leave my machine?Everything is stored locally and encrypted — secrets with AES-256-GCM — with no telemetry, analytics or data sharing, plus a full audit log of all tool executions.
What can it actually do once it is up and running?Chat with it in the browser or via Telegram/Slack while it runs jobs in parallel with isolated contexts. It supports cron schedules, event triggers and webhook handlers for background automation, a heartbeat system for proactive monitoring, self-repair of stuck operations, and persistent memory with hybrid full-text plus vector search.
How does it stop a buggy or malicious tool from leaking my data?Untrusted tools run in WASM sandboxes with capability-based permissions: HTTP only to explicitly allowlisted hosts and paths, secrets injected at the host boundary and never exposed to tool code, plus leak detection, per-tool rate limits and memory/CPU/time caps. External content also passes prompt-injection detection, sanitization and policy rules.
Can I add new tools or integrations to it?Yes — describe what you need and IronClaw builds it as a WASM tool on the fly. It also connects to MCP servers for extra capabilities, and new WASM tools and channels drop in without restarting. Telegram and Slack are installed as extensions and set up on the WebUI Extensions page.
What is OpenClaw, and how is IronClaw related to it?OpenClaw is the project IronClaw reimagines in Rust. Key differences: Rust instead of TypeScript (single native binary), a WASM sandbox instead of Docker for tool isolation, PostgreSQL instead of SQLite for persistence, and a security-first multi-layer design. A FEATUREPARITY.md matrix tracks the parity.
What are similar projects?nullclaw, nanoclaw, taskuary, opensquilla, openfang, lean-ctx, picoclaw, brigade
Which topics is it in?prompt-injection, cron, plugins, ai-assistant, slack, webui, privacy-first, telegram, openclaw, sandbox, wasm, encryption
Creator
nearai
Size
1020 MB
Stars
12.7K
Updated
CommitSep 10Releaseironclaw-v1.4.1Sep 29
Age
8mo
Commits · 90 Days