nearai / ironclaw

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.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. Install via Windows Installer (Windows) Download the Windows Installer and run it. Install via powershell script (Windows) Install via shell script (macOS, Linux, Windows/WSL) Install via Homebrew (macOS/Linux) Compile the source code (Cargo on Windows, Linux, macOS) Install it with , just make sure you have Rust installed on your computer. For **full release** (after modifying channel sources), run to rebuild channels first. Database Setup Configuration Run the setup wizard to configure IronClaw: 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. , ) are written to 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**, **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: See docs/LLM_PROVIDERS.md for a full provider guide. 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 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 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 Development • **Telegram channel**: See docs/TELEGRAM_SETUP.md for set…