ironclaw Documentation

IronClaw is an Agent OS focused on privacy, security and extensibility

12,594 stars Rust Rust 1 file · ~3,384 tokens #codeact#openclaw#rlm#rust#wasm
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy ironclaw on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name ironclaw -p 5432:5432 --restart always pgvector/pgvector:pg16
Configured Services & Ports
⚙️ postgres
image: pgvector/pgvector:pg16
🔌 Ports: 127.0.0.1:5432:5432
docker-compose.yml
yaml (docker-compose.yml) 
# Local development only — do NOT use these credentials in production.
services:
  postgres:
    image: pgvector/pgvector:pg16
    ports:
      - "127.0.0.1:5432:5432"
    environment:
      POSTGRES_DB: ironclaw
      POSTGRES_USER: ironclaw
      POSTGRES_PASSWORD: ironclaw  # dev-only, change for any non-local deployment
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ironclaw"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  pgdata:

1. Project Overview & Quickstart (nearai/ironclaw)

IronClaw

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:

bash
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:

bash
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)

powershell
$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)

bash
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.

bash
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:

bash
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:

bash
ironclaw models set-provider openai --model gpt-5-mini
ironclaw config set openai.api_key

Additional settings use the same command. For example:

bash
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
text
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

text
/* Detailed source-code truncated for AI context efficiency. */

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

bash
# 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

bash
# 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:

  • 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:

at your option.

2. Official Technical Reference & Guides (nearai/docs)

About

This repository contains the official documentation for NEAR AI Cloud, a platform offering developers access to secure, private, verifiable AI models through a unified API.

The site is built and hosted with Mintlify. Content is plain MDX; docs.json holds the navigation, branding, and site settings.

The API Reference tab is generated by Mintlify from api-reference/openapi.json, a vendored copy of the live spec. Refresh it with ./scripts/sync-openapi.py whenever the API changes.

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js >= 20.0.0 (Download)
  • Mintlify CLI: npm i mint

Quick Start

Installation

bash
# Clone the repository
git clone https://github.com/nearai/docs.git
cd docs

# Install the Mintlify CLI (once)
npm i mint

Local Development

bash
# Start the local preview
mint dev

This starts a local preview at http://localhost:3000. Changes are reflected live without restarting the server.

Validate

bash
# Strict build validation (fails on warnings or errors)
mint validate

# Check for broken internal links
mint broken-links

Run both before opening a pull request; CI runs the broken-link check on every PR.

Available Commands

Command Description
mint dev Start the local preview with hot reload
mint validate Validate the build in strict mode
mint broken-links Check for broken links
mint update Update the Mintlify CLI

Deployment

Mintlify deploys automatically from the main branch through the Mintlify GitHub App; every pull request gets a preview deployment. The production domain (docs.near.ai) is configured in the Mintlify dashboard.

Contributing

We welcome contributions to improve our documentation! Here's how you can help:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-improvement)
  3. Make your changes and test locally (mint dev)
  4. Validate (mint validate && mint broken-links)
  5. Commit your changes (git commit -m 'Add amazing improvement')
  6. Push to the branch (git push origin feature/amazing-improvement)
  7. Open a Pull Request

Documentation Guidelines

  • Use clear, concise language
  • Include code examples where applicable
  • Follow the existing documentation structure
  • Test all code snippets before submitting
  • Use proper markdown formatting

Documentation Standards

  • Markdown Files: Use the .mdx extension; a page's URL is its file path (e.g., cloud/quickstart.mdx → /cloud/quickstart)
  • Navigation: Add every new page to the navigation tree in docs.json
  • Code Blocks: Include language identifiers for syntax highlighting; add a filename after the language for a title (```yaml librechat.yaml)
  • Links: Use absolute paths for internal links (e.g., /cloud/quickstart)
  • Images: Store in images/ and reference with absolute paths (e.g., /images/cloud.png)
  • Components: Use Mintlify's built-in components (Card, CardGroup, Tabs, Accordion, Note/Tip/Warning, …) rather than custom React
  • Integration guides: Follow the section contract in .github/INTEGRATION_GUIDE_TEMPLATE.md

Bug Reports & Feature Requests

Found a bug or have a feature request? Please open an issue with:

  • Clear title and description
  • Steps to reproduce (for bugs)
  • Expected vs actual behavior
  • Screenshots (if applicable)

Support

Need help? Reach out through:

License

This project is licensed under the MIT License - see the LICENSE file for details.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#codeact Browse codeact catalog → #openclaw Browse openclaw catalog → #rlm Browse rlm catalog → #rust Browse rust catalog → #wasm Browse wasm catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →