mirror of
https://github.com/outbackdingo/optimclaw.git
synced 2026-08-25 14:53:34 +00:00
Illia PolosukhinandClaude Opus 4.6
a93c7ed893
Channels listed CLI/Telegram/WhatsApp/Slack but only REPL + HTTP are built-in (Telegram/Slack are WASM channels, WhatsApp never existed). Auth section required a manual session token but the actual flow uses OAuth via `ironclaw setup`. Config pointed at a nonexistent refinery.toml, used the wrong default model, and the curl example had the wrong field name. Updated all sections to match the code. Co-Authored-By: Claude Opus 4.6 <[email protected]>
238 lines
9.3 KiB
Markdown
238 lines
9.3 KiB
Markdown
<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, and extensible WASM channels (Telegram, Slack, and more)
|
|
- **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)
|
|
|
|
### Build
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/nearai/ironclaw.git
|
|
cd ironclaw
|
|
|
|
# Build
|
|
cargo build --release
|
|
|
|
# Run tests
|
|
cargo test
|
|
```
|
|
|
|
### Database Setup
|
|
|
|
```bash
|
|
# Create database
|
|
createdb ironclaw
|
|
|
|
# Enable pgvector
|
|
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Run the setup wizard to configure IronClaw:
|
|
|
|
```bash
|
|
ironclaw setup
|
|
```
|
|
|
|
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│ │
|
|
│ └──┬───┘ └──┬───┘ └──────┬───────┘ │
|
|
│ └─────────┴─────────────┘ │
|
|
│ │ │
|
|
│ ┌────▼────┐ │
|
|
│ │ Router │ Intent classification │
|
|
│ └────┬────┘ │
|
|
│ │ │
|
|
│ ┌──────────▼──────────┐ │
|
|
│ │ Scheduler │ Parallel job management │
|
|
│ └──────────┬──────────┘ │
|
|
│ │ │
|
|
│ ┌───────────────┼───────────────┐ │
|
|
│ ▼ ▼ ▼ │
|
|
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
│ │ Worker │ │ Worker │ │ Worker │ LLM reasoning │
|
|
│ └────┬────┘ └────┬────┘ └────┬────┘ │
|
|
│ └───────────────┼───────────────┘ │
|
|
│ │ │
|
|
│ ┌──────────▼──────────┐ │
|
|
│ │ Tool Registry │ │
|
|
│ │ ┌───────────────┐ │ │
|
|
│ │ │ Built-in │ │ │
|
|
│ │ │ MCP │ │ │
|
|
│ │ │ WASM Sandbox │ │ │
|
|
│ │ └───────────────┘ │ │
|
|
│ └─────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 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 |
|
|
| **Workspace** | Persistent memory with hybrid search |
|
|
| **Safety Layer** | Prompt injection defense and content sanitization |
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# First-time setup (configures database, auth, etc.)
|
|
ironclaw setup
|
|
|
|
# Start interactive REPL
|
|
cargo run
|
|
|
|
# With debug logging
|
|
RUST_LOG=ironclaw=debug cargo run
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Format code
|
|
cargo fmt
|
|
|
|
# Lint
|
|
cargo clippy --all --benches --tests --examples --all-features
|
|
|
|
# Run tests
|
|
cargo test
|
|
|
|
# Run specific test
|
|
cargo test test_name
|
|
```
|
|
|
|
## OpenClaw Heritage
|
|
|
|
IronClaw is a Rust reimplementation inspired by [OpenClaw](https://github.com/openclaw/openclaw). See [FEATURE_PARITY.md](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](LICENSE-APACHE))
|
|
- MIT License ([LICENSE-MIT](LICENSE-MIT))
|
|
|
|
at your option.
|