mirror of
https://github.com/outbackdingo/optimclaw.git
synced 2026-08-25 14:53:34 +00:00
b58b421535
* feat(shell): add Low/Medium/High risk levels for graduated approval (#172) - Add `RiskLevel` enum (Low/Medium/High, Ord-comparable) to `tool.rs` and re-export from `tools/mod.rs` - Add `risk_level_for(¶ms) -> RiskLevel` to the `Tool` trait (default: Low); override on `ShellTool` via `classify_command_risk` - Add `classify_command_risk(command: &str) -> RiskLevel` to `shell.rs`: High for NEVER_AUTO_APPROVE patterns, Low for read-only prefixes, Medium for reversible mutations, Medium as the unknown-command default - Add `extract_command_param` helper to de-duplicate JSON extraction - Add `sudo ` to `NEVER_AUTO_APPROVE_PATTERNS` (now classified High) - Wire `risk_level_for` into `requires_approval`: Low → Never, Medium → UnlessAutoApproved, High → Always (uses upstream's new API) - Log risk level at INFO on every tool call in `worker.rs` - Replace `requires_explicit_approval` (simple bool) with the richer `classify_command_risk`; update dispatcher.rs test - Add tests: `test_classify_command_risk_high/low/medium/pipeline`, `test_risk_level_for_via_tool_trait`, updated approval tests Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * style: apply cargo fmt to shell.rs and dispatcher.rs Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * fix(shell): fix pipeline risk aggregation and word-boundary matching Address reviewer feedback: - `classify_command_risk` now iterates ALL pipeline segments and takes the maximum risk, so `echo hello | cargo build` → Medium instead of the previous (wrong) Low - Replace `starts_with` with `matches_command_pattern`: single-word patterns use exact first-token comparison so `lsblk` no longer matches `ls`, `makeself` no longer matches `make`, etc.; multi-word patterns (e.g. `git status`) still use starts_with + space boundary - Drop `--help` / `-h` from LOW_RISK_PATTERNS (can never be first token) - Add `test_classify_command_risk_word_boundary` and extend pipeline test with mixed Low+Medium and unknown-command cases Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * fix(shell): move sed/awk/find from Low to Medium risk `sed -i`, `awk -i inplace`, and `find -delete`/`find -exec rm` can all modify or delete files. Classifying these as Low (auto-approve) was unsafe. Moving to Medium requires UnlessAutoApproved approval, which prompts the user unless they have explicitly enabled auto-approve mode. Fixes review feedback from zmanian on PR #368. Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * fix(shell): update test to use classify_command_risk after requires_explicit_approval removal The rebase brought in upstream commits that removed requires_explicit_approval. Update the mixed-case destructive command test to assert RiskLevel::High via classify_command_risk instead. Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * fix(shell): use word-boundary matching for High-risk patterns to prevent false positives The NEVER_AUTO_APPROVE_PATTERNS check used `contains()` on the full command string, causing false positives: `makeshutdownscript` matched `shutdown`, `nftables-config` matched `nft`, and `passwdqc-check` matched `passwd`. Fix: move the High-risk check inside the per-segment loop and use `matches_command_pattern` (the same word-boundary logic used for Low/Medium), so classification is consistent across all three risk levels. Also remove the trailing spaces from `"nft "` and `"sudo "` in NEVER_AUTO_APPROVE_PATTERNS since `matches_command_pattern` handles word-boundary detection without them. Adds three regression tests for the false-positive cases. Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * fix(shell): address zmanian review — redirect safety + explicit git push pattern Two issues from zmanian's CHANGES_REQUESTED review on PR #368: 1. **Security (Low → UnlessAutoApproved)**: `Low` was mapped to `ApprovalRequirement::Never`, bypassing approval entirely for commands like `cat /etc/shadow > /tmp/out` since the pipeline splitter does not split on shell redirections (`>`, `>>`). Changing to `UnlessAutoApproved` preserves the graduated risk metadata for audit while keeping approval policy conservative until redirect-aware parsing is in place. 2. **Minor (explicit git push pattern)**: `git push origin feature-branch` fell through to the unknown-command Medium default rather than matching an explicit pattern. Adding `"git push"` to MEDIUM_RISK_PATTERNS makes the classification intentional. Force-push variants (`git push --force`, `git push -f`) remain in NEVER_AUTO_APPROVE_PATTERNS (High). Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * test(shell): add regression tests for redirect bypass and git push pattern fixes Two regression tests for the fixes in the previous commit: 1. `test_low_risk_with_redirect_not_never` — verifies that Low-risk commands containing shell redirections (`echo x > /etc/passwd`, `cat /etc/shadow > /tmp/out`, etc.) return `UnlessAutoApproved`, not `Never`. Before the fix, `Low` mapped to `Never` which would have allowed these writes to bypass approval entirely. 2. `test_git_push_explicit_medium_pattern` — verifies that `git push origin branch` is classified `Medium` via the explicit `MEDIUM_RISK_PATTERNS` entry (not the unknown-command fallthrough). Force variants (`--force`, `-f`) remain `High`. Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * test(shell): add integration regression tests for redirect bypass and git push Covers the two fixes from the previous commits at the integration-test level (tests/ directory) to ensure the CI regression-test gate is satisfied: 1. `low_risk_command_with_redirect_is_unless_auto_approved` -- verifies that Low-risk commands containing shell redirections return UnlessAutoApproved, not Never (the pre-fix behaviour that allowed redirect-based bypass). 2. `git_push_is_unless_auto_approved` -- verifies git push is Medium risk (UnlessAutoApproved) via the explicit pattern, not unknown-command fallthrough. 3. `git_push_force_requires_always_approval` -- verifies force-push variants remain High risk (Always approval required). Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * refactor(test): move inline assertions to tests/ to satisfy no-panics CI check The project's no-panics CI check (code_style.yml) scans src/**/*.rs for assert_eq!/assert_ne!/.unwrap() in added lines. Moving classify_command_risk tests to tests/shell_risk_regression.rs and adding // safety: comments on the two remaining assertions in dispatcher.rs eliminates all false positives. - Remove test_classify_command_risk_* and related functions from shell.rs - Remove test_low_risk_with_redirect_not_never and test_git_push_* from shell.rs (covered by integration tests in tests/) - Expand tests/shell_risk_regression.rs with full coverage via public API - Add // safety: test code comments on dispatcher.rs assert lines Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * fix(shell): address review findings — force-with-lease, test runners, Display - Add `git push --force-with-lease` to NEVER_AUTO_APPROVE_PATTERNS — the word-boundary matching in matches_command_pattern would not match it against the existing `git push --force` pattern (next char is `-`, not space), causing it to fall through to Medium instead of High. - Move `cargo test`, `npm test`, `npm run test`, `yarn test` from LOW_RISK_PATTERNS to MEDIUM_RISK_PATTERNS — test runners execute arbitrary code and can have side effects (file creation, network calls, process spawning). - Add `Display` impl for `RiskLevel` (lowercase: low/medium/high) and switch worker logging from `?risk` (Debug) to `%risk` (Display) for cleaner audit logs. - Fix integration test helper to call `register_dev_tools()` since ShellTool is registered there, not in `register_builtin_tools()`. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> --------- Co-authored-by: Claude Sonnet 4.6 <[email protected]> Co-authored-by: [email protected] <[email protected]>
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)
irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex
Install via shell script (macOS, Linux, Windows/WSL)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh
Install via Homebrew (macOS/Linux)
brew install ironclaw
Compile the source code (Cargo on Windows, Linux, macOS)
Install it with cargo, just make sure you have Rust installed on your computer.
# 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
# Create database
createdb ironclaw
# Enable pgvector
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
Configuration
Run the setup wizard to configure IronClaw:
ironclaw onboard
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. DATABASE_URL, LLM_BACKEND) are
written to ~/.ironclaw/.env 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, GitHub Copilot, 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:
# Example: MiniMax (built-in, 204K context)
LLM_BACKEND=minimax
MINIMAX_API_KEY=...
# Example: OpenAI-compatible endpoint
LLM_BACKEND=openai_compatible
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=sk-or-...
LLM_MODEL=anthropic/claude-sonnet-4
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
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
# First-time setup (configures database, auth, etc.)
ironclaw onboard
# Start interactive REPL
cargo run
# With debug logging
RUST_LOG=ironclaw=debug cargo run
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
- Telegram channel: See docs/TELEGRAM_SETUP.md for setup and DM pairing.
- Changing channel sources: Run
./channels-src/telegram/build.shbeforecargo buildso the updated WASM is bundled.
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:
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT License (LICENSE-MIT)
at your option.