GO — Healthy across the board

• Last commit today
• 13 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 66% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

IronClaw is a local-first Agent OS built in Rust that executes AI agents with cryptographic isolation, credential injection, and WASM/Docker sandboxing. It solves the problem of running untrusted AI tools without exposing credentials, personal data, or allowing prompt injection attacks—by architecting capability-based security into the core dispatcher, authorization layer, and WASM runtime (crates/ironclaw_wasm, crates/ironclaw_secrets, crates/ironclaw_authorization). Monorepo (Cargo workspace with 25 crates) organized by domain: crates/ironclaw_engine is the orchestrator, crates/ironclaw_wasm and crates/ironclaw_dispatcher handle sandboxing, crates/ironclaw_secrets encrypts credentials, crates/ironclaw_gateway provides HTTP+WebSocket frontend, crates/ironclaw_tui offers CLI. Multi-channel support in channels-src/ (Discord, Telegram, Slack, etc., excluded from main workspace). Tools extensible via tools-src/.

Privacy-conscious engineers and teams deploying AI agents in production who need cryptographic guarantees about data isolation, credential protection, and auditability. Also: open-source AI researchers building extensible agent frameworks and security researchers studying AI agent threat models.

Actively developed (v0.27.0, Rust 1.92, 2024 edition); substantial codebase (~20.5MB Rust) with 25+ core crates and CI/CD pipelines (.github/workflows). Has security-focused test rules (.claude/rules/testing.md) and linting (code_style.yml). Early-stage adoption (production-ready core, but ecosystem still maturing—tool integrations in tools-src/ and channels-src/ are mostly excluded from workspace, suggesting incomplete bundling).

Moderate risk: large attack surface (WASM, network, secrets management); security is core value but nascent ecosystem means fewer audit eyes. Dependency on cutting-edge Rust async (tokio 1.x, complex feature flags). Single team (NEAR AI) maintains most code; community contributions exist but core maintainability concentration. Breaking changes possible during 0.x versioning.

Active development on security hardening (rules/ contain evolving standards for error-handling, safety-and-sandbox, tool-evidence), gateway/streaming features (sse-event command), and documentation/onboarding (skills/ for video architecture, mintlify docs). PR review workflow and issue triage are codified (.claude/commands/review-pr.md, triage-issues.md). Version ~0.27 suggests rapid iteration.

git clone https://github.com/nearai/ironclaw.git
cd ironclaw
cp .env.example .env
cargo build --release
cargo run --bin ironclaw  # main binary

Dependencies: Rust 1.92+, tokio async runtime, PostgreSQL (PLpgSQL in repo suggests DB requirement—check .env.example). Pre-commit hooks in .githooks/.

Daily commands:

# Development
cargo build
cargo test --all

# CLI (inferred from crates/ironclaw_tui)
cargo run --bin ironclaw -- [args]

# With Docker
docker build -t ironclaw .
docker run -e DATABASE_URL=postgres://... ironclaw

# Web gateway (crates/ironclaw_gateway suggests HTTP server)
cargo run --bin ironclaw --features gateway

See .config/nextest.toml for test runner config.

• crates/ironclaw_engine: Core agent orchestration and execution logic; entry point for all agent runs
• crates/ironclaw_wasm: WASM sandbox runtime and capability-based permissions for untrusted tools
• crates/ironclaw_secrets: Credential encryption, injection at host boundary, and leak detection system
• crates/ironclaw_authorization: Policy enforcement, capability-based access control, and principal/resource model
• crates/ironclaw_dispatcher: Request routing, sandboxed tool invocation, and isolation orchestration
• crates/ironclaw_gateway: HTTP/WebSocket API, web UI, real-time SSE streaming for agents
• .claude/rules: Codified design rules for security, error handling, types, testing, and tool evidence—consulted during reviews
• .github/workflows: CI/CD pipelines: code style, coverage, docker builds, and Claude-driven automated reviews

Adding a tool: follow .claude/commands/add-tool.md and place in tools-src/[tool-name]/. Security rule changes: edit .claude/rules/[domain].md (e.g., safety-and-sandbox.md for sandbox behavior). New capability: add crate under crates/ironclaw_[feature]/, export from crates/ironclaw_common. Fixing issues: use .claude/commands/fix-issue.md; PRs trigger code review workflow. New gateway features: modify crates/ironclaw_gateway, update .claude/rules/gateway-events.md.

1. PostgreSQL dependency: DATABASE_URL environment variable required; schema setup not obvious in this snippet—check migrations/ or .env.example. 2. WASM configuration: crates/ironclaw_wasm likely requires runtime (wasmtime) binary or feature flags—missing from the Cargo.toml snippet; check actual file. 3. Credential leakage tests critical: crates/ironclaw_secrets has hardened rules; log output can expose secrets if not carefully tested. 4. Pre-commit hooks enforced: .githooks/ are installed; commits may be blocked by clippy/tests without understanding the .git/hooks setup. 5. Excluded crates still referenced: tools-src/ and channels-src/ are excluded from workspace but may be imported as dependencies; build may fail if Git submodules or features are incomplete.

• Capability-Based Security — IronClaw's authorization model (crates/ironclaw_authorization, crates/ironclaw_capabilities) grants fine-grained permissions to sandboxed tools rather than trusting them; foundational to understanding why untrusted tools cannot exfiltrate data
• WebAssembly (WASM) Sandbox — crates/ironclaw_wasm isolates untrusted tool code in a memory-safe runtime with no access to host syscalls; critical for executing third-party tools without privilege escalation
• Credential Injection at Host Boundary — crates/ironclaw_secrets encrypts credentials and injects them only at syscall/network boundary (not into tool memory), preventing accidental exfiltration via tool output or logging
• Prompt Injection Defense — crates/ironclaw_safety implements pattern detection, content sanitization, and policy enforcement to prevent adversarial text in tool outputs from hijacking agent behavior
• Monorepo Workspace Pattern — 25-crate Cargo workspace (Cargo.toml members list) enables shared dependencies, atomic versioning, and clear separation of concerns (engine, dispatcher, gateway, etc.) while maintaining single build and test suite
• Server-Sent Events (SSE) Streaming — crates/ironclaw_gateway uses SSE for real-time agent output to web clients (see .claude/commands/add-sse-event.md); enables responsive UI without full WebSocket complexity
• Heartbeat & Proactive Monitoring — IronClaw's heartbeat system detects stalled/hung agents and enables background automation (Routines); critical for multi-channel deployment (Telegram, Slack, Discord) where agent must appear responsive

• mozilla/wasm-bindgen — Rust↔WASM FFI library; critical for crates/ironclaw_wasm host bindings and capability exposure
• bytecodealliance/wasmtime — Industry-standard WASM runtime underlying crates/ironclaw_wasm sandbox isolation
• denoland/deno — Parallel permission-based sandboxing design (filesystem, network, subprocess) that influenced IronClaw's capability model
• openai/evals — Agent testing framework; relevant for validating IronClaw tools and prompt injection defenses
• modularml/mojo — Alternative safe-by-default language runtime; comparison point for IronClaw's Rust + WASM security approach

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for IronClaw gateway event streaming

The repo has comprehensive gateway event rules (.claude/rules/gateway-events.md) and SSE event commands (.claude/commands/add-sse-event.md), but there's no dedicated integration test suite for the gateway crate (crates/ironclaw_gateway). Given the complexity of event streaming, SSE handling, and the safety-critical nature of this Agent OS, integration tests validating event flow, error handling, and concurrent event processing would catch regressions early and serve as living documentation.

• [ ] Create crates/ironclaw_gateway/tests/gateway_events_integration.rs
• [ ] Add tests for SSE stream initialization, event serialization, and client disconnection handling
• [ ] Test concurrent event publishing across multiple subscribers per .claude/rules/gateway-events.md
• [ ] Integrate into .github/workflows/test.yml and nightly-deep-ci.yml for regression detection
• [ ] Reference existing patterns in other crate test directories

Add missing WASM sandbox security property-based tests

The repo has safety-and-sandbox rules (.claude/rules/safety-and-sandbox.md) and a WASM crate (crates/ironclaw_wasm), but there are no visible property-based tests validating that untrusted WASM modules cannot escape the sandbox or perform unauthorized system calls. Using quickcheck or proptest to generate malicious WASM bytecode and verify containment would be a high-value security contribution that strengthens the 'privacy, security and extensibility' value prop.

• [ ] Add dependency on proptest to crates/ironclaw_wasm/Cargo.toml
• [ ] Create crates/ironclaw_wasm/tests/sandbox_properties.rs with property-based tests
• [ ] Generate random WASM modules that attempt memory escapes, illegal syscalls, and resource exhaustion
• [ ] Verify all attempts are properly trapped and isolated per safety-and-sandbox.md rules
• [ ] Include in .github/workflows/nightly-deep-ci.yml for thorough security validation

Implement missing authorization policy validation tests for capabilities crate

The repo has authorization (crates/ironclaw_authorization), capabilities (crates/ironclaw_capabilities), and trust (crates/ironclaw_trust) crates, plus tool-evidence rules (.claude/rules/tool-evidence.md), but there's no visible test suite verifying that capabilities are correctly enforced against authorization policies in realistic scenarios. Adding policy-based tests (e.g., 'user X with role Y should/shouldn't access tool Z') would validate the security model and prevent capability escalation bugs.

• [ ] Create crates/ironclaw_authorization/tests/capability_enforcement.rs
• [ ] Define test fixtures for roles, capabilities, and authorization policies
• [ ] Write parameterized tests covering grant/deny/audit scenarios per tool-evidence.md
• [ ] Test interaction between ironclaw_trust decisions and ironclaw_authorization enforcement
• [ ] Add to .github/workflows/test.yml and document in COVERAGE_PLAN.md

• Add integration tests for crates/ironclaw_secrets credential injection with crates/ironclaw_dispatcher—test that a malicious WASM tool cannot read injected credentials even on a successful sandbox breakout attempt.
• Document the gateway WebSocket/SSE event protocol in .claude/skills/mintlify-docs/ with concrete examples (connect, subscribe to agent run, receive heartbeat, handle errors)—currently only code exists.
• Add deny/allowlist validation tests to crates/ironclaw_network for endpoint allowlisting feature—verify that HTTP requests to non-approved hosts are rejected with clear error messages.

• High · Incomplete Tokio Dependency Configuration — Cargo.toml - [dependencies] section. The Cargo.toml shows an incomplete tokio dependency declaration with 'features = ["full"]' but the line appears truncated in the dependency specification. This could lead to missing security-critical features or runtime issues if the dependency resolution fails. Fix: Ensure the tokio dependency is fully specified with all required features. Verify the complete Cargo.toml syntax is correct and all dependencies are properly closed with closing brackets.
• Medium · Secrets Exposure in Environment Configuration Example — .env.example. The .env.example file contains commented-out placeholder values for sensitive credentials including ANTHROPIC_API_KEY, ANTHROPIC_OAUTH_TOKEN, and OPENAI_API_KEY. While these are placeholders, developers may inadvertently commit actual secrets by copying .env.example to .env without proper sanitization. Fix: 1) Ensure .env is in .gitignore (verify in .gitignore file). 2) Add pre-commit hooks to detect potential secret commits. 3) Document that developers should never commit .env files with real credentials. 4) Consider using environment-variable validation on startup to warn about missing secrets.
• Medium · High Database Connection Pool Default for Multi-Tenant — .env.example - DATABASE_POOL_SIZE. The DATABASE_POOL_SIZE is set to 30 by default for multi-tenant deployments. This could lead to resource exhaustion or connection limit issues in certain deployment scenarios, especially if multiple instances are running against a single database. Fix: 1) Implement dynamic pool sizing based on deployment type (single-user vs multi-tenant). 2) Document recommended pool sizes for different scenarios. 3) Add monitoring/alerts for connection pool saturation. 4) Implement connection timeout and retry logic.
• Medium · No Explicit Security Headers Configuration Visible — Dockerfile - port 3000 exposure. The Dockerfile and configuration files do not show explicit security headers configuration (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, etc.) for the HTTP API running on port 3000. Fix: 1) Implement comprehensive security headers middleware. 2) Document required headers for the gateway service. 3) Add HTTPS/TLS enforcement. 4) Configure CORS policies explicitly.
• Medium · Multi-Stage Docker Build Without Non-Root User — Dockerfile - runtime stage. The Dockerfile does not specify a non-root user for the runtime stage, which means containers will run as root by default. This increases the blast radius if a container is compromised. Fix: 1) Add a non-root user creation in the runtime stage. 2) Use USER directive to switch to that user before running the application. 3) Set appropriate file permissions for the application directory.
• Medium · LLM Request Timeout Not Enforced by Default — .env.example - LLM_REQUEST_TIMEOUT_SECS. The LLM_REQUEST_TIMEOUT_SECS is commented out with only a note that it should be increased for local LLMs. No default timeout is enforced, which could lead to hanging requests or denial-of-service scenarios. Fix: 1) Set a sensible default timeout (e.g., 120 seconds). 2) Make timeout configuration mandatory with validation. 3) Document timeout implications for different LLM backends. 4) Implement circuit breaker patterns for LLM calls.
• Low · Rust Edition 2024 May Have Limited Tooling Support — Cargo.toml - edition field. The Cargo.toml specifies edition = '2024', which is a future edition. While this is intentional for forward compatibility, it may have limited IDE/tooling support and could introduce unexpected breaking changes. Fix: 1) Document the requirement for Rust 1.92+ explicitly in CONTRIBUTING.md. 2) Ensure all CI/CD pipelines test against the correct Rust version. 3) Monitor Rust release notes for any breaking changes in the 2024 edition.
• Low · Multiple License Files Without Clear Precedence — undefined. The project includes both LICENSE-APACHE and LICENSE-MIT files. While the Cargo.toml correctly specifies 'MIT OR Apache-2.0', the presence Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/nearai/ironclaw shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live nearai/ironclaw repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nearai/ironclaw.

What it runs against: a local clone of nearai/ironclaw — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in nearai/ironclaw | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of nearai/ironclaw. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/nearai/ironclaw.git
#   cd ironclaw
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of nearai/ironclaw and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "nearai/ironclaw(\\.git)?\\b" \\
  && ok "origin remote is nearai/ironclaw" \\
  || miss "origin remote is not nearai/ironclaw (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/nearai/ironclaw"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.