mirror of
https://github.com/outbackdingo/optimclaw.git
synced 2026-08-25 14:53:34 +00:00
Ilgın KanatandGitHub
115b7f38fe
* feat: Implement DM pairing for channels - Introduced a new pairing system to manage direct messages from unknown senders. - Added `PairingStore` to handle pending requests and allowlist management. - Implemented CLI commands for listing and approving pairing requests. - Updated Telegram channel to utilize the new pairing logic, including workspace paths for storing pairing data. - Enhanced WASM channel integration to support pairing functionality. This feature enhances security by requiring approval for unknown senders before they can interact with the agent. * Enhance Telegram channel support with media captioning and DM pairing features - Added support for media captions in Telegram messages, allowing for richer content handling. - Updated message processing to utilize either text or caption, improving message flexibility. - Enhanced DM pairing functionality to include approval and listing capabilities for direct messages. - Updated feature parity documentation to reflect new capabilities and improvements in Telegram integration. * Update README and BUILDING_CHANNELS documentation for Telegram channel integration - Enhanced README with instructions for building and running the Telegram channel, including a note on running `./scripts/build-all.sh` for full releases. - Added detailed steps in BUILDING_CHANNELS.md for building and deploying the Telegram channel, emphasizing the need to run `./channels-src/telegram/build.sh` before building the main crate to ensure updated WASM is included. - Updated CLI module to expose a new command for pairing with store functionality. * Implement build script for Telegram channel WASM and enhance pairing error handling - Added a new `build.rs` script to automate the compilation of the Telegram channel's WASM binary from source, ensuring reproducible builds and emphasizing supply chain security by preventing committed binaries. - Updated `BUILDING_CHANNELS.md` to reflect the new build process and the importance of not committing compiled binaries. - Enhanced error handling in the pairing approval process to include rate limiting for failed attempts, improving security and user feedback. * Remove Telegram channel WASM binary file as part of the build process cleanup, ensuring no committed binaries are present in the repository.
255 lines
11 KiB
Markdown
255 lines
11 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, 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](https://github.com/pgvector/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
|
|
```
|
|
|
|
For **full release** (after modifying channel sources), run `./scripts/build-all.sh` to rebuild channels first.
|
|
|
|
### 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 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
|
|
|
|
```bash
|
|
# First-time setup (configures database, auth, etc.)
|
|
ironclaw onboard
|
|
|
|
# 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
|
|
createdb ironclaw_test
|
|
cargo test
|
|
|
|
# Run specific test
|
|
cargo test test_name
|
|
```
|
|
|
|
- **Telegram channel**: See [docs/TELEGRAM_SETUP.md](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](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.
|