IronClaw

LLM-powered autonomous agent for the NEAR AI marketplace

Features • Installation • Configuration • Architecture • Security

---

Features

• Multi-channel input - CLI, HTTP webhooks, Slack, Telegram
• Parallel job execution - Concurrent task processing with isolated contexts
• Extensible tools - Built-in tools + MCP protocol + WASM sandbox
• Persistent memory - Hybrid search (FTS + vector) with chunked documents
• Prompt injection defense - Pattern detection, content sanitization, policy enforcement
• Self-repair - Automatic detection and recovery of stuck jobs
• Heartbeat system - Proactive periodic execution for background tasks

Installation

Prerequisites

• Rust 1.85+
• PostgreSQL 15+ with pgvector extension
• NEAR AI session token

Build

# Clone the repository
git clone https://github.com/nearai/near-agent.git
cd near-agent

# Build
cargo build --release

# Run tests
cargo test

Database Setup

# Create database
createdb near_agent

# Enable pgvector
psql near_agent -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Run migrations
refinery migrate -c refinery.toml

Configuration

Copy .env.example to .env and configure:

# Required
DATABASE_URL=postgres://user:pass@localhost/near_agent
NEARAI_SESSION_TOKEN=sess_...

# Optional: Enable channels
SLACK_BOT_TOKEN=xoxb-...
TELEGRAM_BOT_TOKEN=...
HTTP_PORT=8080

Environment Variables

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string	Yes
NEARAI_SESSION_TOKEN	NEAR AI authentication token	Yes
NEARAI_MODEL	Model to use (default: claude-3-5-sonnet)	No
AGENT_MAX_PARALLEL_JOBS	Max concurrent jobs (default: 5)	No
SECRETS_MASTER_KEY	32+ byte key for secret encryption	For secrets

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Channels                                 │
│  ┌─────┐  ┌──────┐  ┌───────┐  ┌──────────┐                    │
│  │ CLI │  │ HTTP │  │ Slack │  │ Telegram │                    │
│  └──┬──┘  └──┬───┘  └───┬───┘  └────┬─────┘                    │
│     └────────┴──────────┴───────────┘                           │
│                         │                                        │
│                    ┌────▼────┐                                  │
│                    │  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

Security

WASM Sandbox

Untrusted tools run in a sandboxed WASM environment with:

• 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
• Leak detection - Scans requests and responses for secret exfiltration
• Rate limiting - Per-tool request limits (per-minute and per-hour)
• 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

• Pattern-based detection of injection attempts
• Content sanitization and escaping
• Policy rules with severity levels (Block/Warn/Review/Sanitize)
• Tool output wrapping for LLM context

Usage

CLI Mode

# Start interactive CLI
cargo run

# With debug logging
RUST_LOG=near_agent=debug cargo run

HTTP Server

# Start with HTTP webhook server
HTTP_PORT=8080 cargo run

# Send a request
curl -X POST http://localhost:8080/webhook \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, agent!"}'

Development

# Format code
cargo fmt

# Lint
cargo clippy --all --benches --tests --examples --all-features

# Run tests
cargo test

# Run specific test
cargo test test_name

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.