ironclaw

The Problem

Enterprises that want a locally‑hosted AI assistant often have to choose between feature‑rich but opaque services and brittle home‑grown scripts. The lack of a privacy‑first, extensible runtime forces teams to build their own sandboxing, credential handling, and multi‑channel glue, duplicating effort and exposing secrets.

What This Does

ironclaw delivers a self‑contained Rust stack that runs a personal AI agent behind a WASM sandbox and a set of channel adapters (Discord, Slack, Telegram, WhatsApp, Web). Core logic lives in src/ (284 files, 271 code files) while each channel lives under channels‑src/<name>/src/lib.rs. The Dockerfiles (Dockerfile, Dockerfile.test, Dockerfile.worker) pack the whole system for isolated deployment. Configuration lives in .env.example and src/config/secrets.rs (the only file flagged for secret‑shaped paths).

How It Is Wired

Execution starts in three top‑level entry points discovered by static analysis:

run and execute are invoked only by the worker binary; they bootstrap the agent scheduler, LLM driver, and tool manager. The call graph shows execute → is_authenticated → .exists(user_id, &server_config.token_secret) (crypto), while run → store → tx.execute("DELETE FROM wasm_channels …") writes to PostgreSQL. The network outbound path is start → run_checked → command.output().context (subprocess) and src/channels/wasm/wrapper.rs (injects credentials then calls remote services).

Key hubs:

• src/agent/worker.rs – 55 functions, 7 types, called from 17 files, performs model inference.
• src/agent/routine.rs – 29 functions, 8 types, called from 67 files, handles routine parsing and config conversion.
• src/context/memory.rs – 43 functions, 3 types, called from 64 files, manages in‑memory and persistent context.

The internal call graph contains 6 000 resolved edges, but no circular imports. The most widely used utilities are Err (231 call sites) and is_empty (223). Because these utilities are pure Rust Result helpers, changing them has a large blast radius.

External side‑effects are limited to:

• Crypto/secret ops – 89 functions (e.g., token secret lookup, credential injection).
• Database I/O – 49 functions (SQL via tx.execute).
• Network I/O – 16 functions (HTTP client, subprocess).

No framework callbacks appear in the resolved graph, so the exact wiring of HTTP routes (src/channels/web/server.rs) is not captured, but the file is listed under “most connected” for its SSE/WebSocket handlers.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/ironclaw.git
cd ironclaw

# Build the worker binary (requires Rust 1.85+)
cargo build --release

# Run the container (Dockerfile builds the full stack)
docker build -t ironclaw:latest .
docker run -d \
  -e DATABASE_URL=postgres://user:pass@db/ironclaw \
  -e TOKEN_SECRET=$(openssl rand -hex 32) \
  -p 8080:8080 ironclaw:latest

Configuration – copy .env.example to .env and fill DATABASE_URL, TOKEN_SECRET, and any channel‑specific tokens (Discord, Slack, etc.). The secret handling code lives in src/config/secrets.rs.

Running the service – the binary produced by cargo build launches the worker (src/agent/worker.rs). The web UI is served from src/channels/web/static/app.js via the HTTP server in src/channels/web/server.rs.

Real‑World Use

A security‑conscious team can deploy the Docker image behind their internal network, point the Telegram channel adapter at their bot token, and store all conversation logs in an encrypted PostgreSQL instance. Custom tools are compiled to WASM, dropped into tools-src/, and automatically loaded by the plugin manager (src/extensions/manager.rs) without restarting the service.

Code Health & Issues

High – Pin GitHub Actions to commit SHAs (.github/workflows/*). High – Do not discard exit codes of critical steps (.github/workflows/release.yml). High – Pushes should target a PR branch, not the default (release.yml). Medium – Declare least‑privilege GITHUB_TOKEN permissions (regression-test-check.yml). Medium – Enable Dependabot or Renovate for 15 manifests. Medium – Pin Docker base images by digest (Dockerfile). Medium – Add a dependency‑vulnerability scan to CI. Low – Set timeout‑minutes on workflow jobs (regression-test-check.yml).

Static analysis also reports high cognitive load: deep nesting (max depth 8) and duplicated 6‑line blocks across the channel adapters, plus oversized files (src/agent/dispatcher.rs, src/agent/thread_ops.rs, channels-src/telegram/src/lib.rs) exceeding 1 800 lines each. Refactoring these hotspots will improve maintainability.

The Bottom Line

ironclaw provides a well‑structured, privacy‑first AI assistant platform with solid Rust foundations and Docker portability. The codebase is functional but suffers from deep nesting, duplicated channel logic, and large monolithic files that increase change risk. It is suitable for teams that need an on‑premise AI runtime and are prepared to invest in refactoring and CI hardening.