DOCSEARCHbyAlgolia
Submit Docs

IronClaw Documentation

repository·main·Indexed 27 days ago

https://github.com/nearai/ironclaw

A secure, personal AI assistant designed for local execution with a focus on data sovereignty. IronClaw utilizes WASM sandboxing and advanced prompt injection defenses to enable the safe creation and execution of custom tools. The project includes a WebUI v2 frontend, a SILK v3 audio decoder, and a modular Rust-based architecture centered on narrow authority, policy gates, and capability hosts.

Tokens
237.5K
Snippets
351
Records
1.2K
Agent score
95%

What's inside IronClaw

  1. Overview of ironclaw_webui

    main
    The ironclaw_webui crate is the WebUI host stack for IronClaw Reborn. It transforms the ironclaw_reborn_composition product/API surface into a running WebChat v2 HTTP server. It manages route handlers, the Single-Page App (SPA) bundle, gateway assembly, middleware, the server loop, and host-side authentication. It sits in the products layer and is typically driven by the ironclaw binary.

  2. Overview of the Portfolio Keeper skill

    main

    The portfolio skill is designed for cross-chain DeFi portfolio discovery, rebalancing suggestions, and NEAR Intent construction. It activates when a user provides a wallet address (supporting 0x... Ethereum-style, .near, or .eth patterns) or asks about topics like yield, APY, rebalancing, or positions.

    Key Capabilities:

    • Aggregates positions across all of a user's addresses into a single per-user portfolio project.
    • Runs recurring keeper missions to monitor and suggest changes.
    • Produces unsigned NEAR Intent bundles for user-accepted moves.

    Security Constraints:

    • No Private Keys: The skill never holds private keys. All execution paths produce unsigned intents only; signing must occur in the user's wallet.
    • Read-only/Unsigned: All portfolio.* operations are strictly read-only or produce unsigned artifacts.

  3. Overview of the Telegram Extension Design

    main

    Note: Superseded Design

    IMPORTANT: This design specification is superseded by the unified manifest-driven extension runtime. For current implementation details, refer to docs/reborn/extension-runtime/overview.md.

    Summary

    The Telegram extension allows Telegram bots to serve as a first-class IronClaw entrypoint.

    Key Capabilities:

    • Admins: Configure a single Telegram bot per deployment via the Channels tab (requires a bot token).
    • Users: Install the telegram extension. Users pair with the bot via a deep link (https://t.me/<bot_username>?start=<CODE>), which automatically resumes blocked threads and makes the state active.
    • Interaction: Once paired, DMs to the bot function as a full IronClaw entrypoint for continuous conversation and proactive delivery.

    Limitations:

    • No telegram.* tools: IronClaw cannot act on the user's behalf (no MTProto/link-device support).
    • DMs Only: Group messages, channel_post, edited messages, and inline queries are ignored.
    • Webhook Only: Uses webhooks for transport; no long-polling support.

  4. Overview of IronClaw Architecture Components

    main

    IronClaw is composed of several core components that manage the agent lifecycle and security:

    ComponentPurpose
    Agent Loop (Цикл агента)Core message processing and task coordination
    Router (Роутер)Classification of user intent (command, query, task)
    Scheduler (Планировщик)Manages parallel task execution with priorities
    Worker (Воркер)Executes tasks involving LLM reasoning and tool calls
    Orchestrator (Оркестратор)Manages container lifecycles, LLM proxying, and task authentication
    Web Gateway (Веб-шлюз)Browser interface for chat, memory, tasks, logs, extensions, and routines
    Routine Engine (Движок рутин)Background tasks: scheduled (cron) and reactive (events, webhooks)
    WorkspacePersistent memory with hybrid search
    Security Layer (Слой безопасности)Prompt injection protection and content sanitization

  5. Overview of Trace Commons Trace Inspection

    main

    Trace inspection allows users to view their submitted Trace Commons traces (including a list and scrubbed content) directly from the IronClaw web UI. The data is fetched per-user from the server using the instance device bearer, providing a remote view that complements the local held-trace review.

    Architecture Flow:

    1. TraceClientHost performs an account-traces fetch using a per-user bearer.
    2. The product_workflow services facade provides a trace_account_traces(caller) method.
    3. The webui_v2 handler exposes the GET /api/webchat/v2/traces/account endpoint.
    4. A React hook/component renders the results in the Trace Commons settings tab.

    Security Note: The scope of the data is always derived from the authenticated caller, never from the request itself.

  6. Understand IronClaw security and encryption

    main

    IronClaw uses AES-256-GCM with per-secret HKDF-SHA256 derived keys for secrets encryption.

    • Master key: Resolved from SECRETS_MASTER_KEY env var or OS keychain.
    • Storage format: nonce (12B) || ciphertext || tag (16B).
    • Zero-exposure: Plaintext is never logged, included in debug output, returned in API responses, or sent to LLM conversations.
    • Auth Cache: Uses a bounded LRU cache (1024 entries, 60s TTL). Note that user suspension or token revocation may take up to 60 seconds to propagate.

  7. Understand the Slack Integration Model (Model B)

    main

    The Slack integration is split into two distinct, runtime-incompatible components. Users interact with the tools extension, while operators manage the bot service via configuration.

    ComponentRoleProvisioning / Installation
    slack_botThe entrypoint bot service. It is hidden from the user catalog.Provisioned by operator via config ([slack].enabled + bot token / signing secret).
    slackThe visible, user-installable tools extension.Installed by the user via slack_personal OAuth.

    Identity Binding: The bot and tools are linked at the identity layer. A user's DM runs with their permissions only if they have completed slack_personal OAuth, which binds their Slack ID to their Reborn user identity.

  8. Understand the Reborn Kernel Boundary

    main

    The Reborn kernel acts as the architectural security perimeter for IronClaw. It is defined by its role in mediating and securing privileged operations rather than by the specific product behaviors it performs.

    Key terminology:

    • kernel: The architectural security boundary.
    • ironclaw_host_runtime: The current concrete composition crate for kernel-facing services and adapters.

    Developers should note that privileged operations must cross kernel-mediated ports. There are no private back doors for shipped loops or first-party code; all privileged effects must be mediated by the kernel.

  9. Understand the Auth Engine (AUTH) architecture

    main

    The IronClaw Auth Engine is a unified system that implements oauth2_code and api_key authentication without per-vendor code paths in the extension ABI. It uses a single AuthEngine (from ironclaw_auth::AuthEngine) to handle all providers.

    Key architectural constraints:

    • Host-Constructed URLs: The host constructs the authorize URL; recipes cannot override parameters like state, redirect_uri, PKCE, client_id, response_type, or scope.
    • Security Enforcement: The engine enforces State/CSRF, PKCE, TTL, and callback replay protection.
    • Scope Validation: Requested scopes are validated against a 'recipe ceiling'; any attempt to widen scopes is rejected before the vendor call.
    • Token Exchange: Supports post_body and basic authentication. Response fields are extracted using bounded JSON pointers.
    • Secret Management: All grants and secrets are encrypted at rest via ironclaw_secrets::SecretStore and are never echoed to the UI or adapters.

  10. Channel Outbound (OUT) Architecture and Delivery Intents

    main

    The Unified Extension Runtime uses a centralized coordinator for all outbound communication. All outbound intents must enter this single coordinator to ensure policy enforcement and prevent direct product-to-channel sends.

    There are eight DeliveryIntent types, which are categorized into two policy classes:

    1. Policy-class (deliver): High-priority delivery intents.
    2. Notice-class (deliver_notice): Notification-style intents.

    Cross-class calls (e.g., a notice-class intent attempting to trigger a policy-class action) are strictly rejected by the coordinator. The generic observer/driver must emit exclusively through RunDeliveryServices.coordinator.

  11. Understand Reborn Storage Placement Rules

    main

    Reborn uses a hybrid storage model to determine where durable state is stored. This prevents forcing all records into JSON files or creating a single omniscient data store.

    • File-shaped content and virtual path authority: Stored in RootFilesystem, ScopedFilesystem, or CompositeRootFilesystem.
    • Structured, query-heavy, control-plane, or security-sensitive records: Stored in typed repositories owned by the specific service domain.
    • Derived data (chunks, search indexes, embeddings, projections): Stored in the owning service, indexer, or projection layer.

  12. Understand the Unified Extension Runtime Implementation Plan

    main

    This document is a superseded migration record detailing the historical implementation plan for the Unified Extension Runtime. It is intended for architectural context rather than current implementation guidance.

    Important: For current implementation details, refer to:

    • docs/reborn/extension-runtime/overview.md (The primary model)
    • crates/ironclaw_extensions (Live crate code)
    • crates/ironclaw_extension_host (Live crate code)
    • crates/ironclaw_product (Live crate code)

    Key Architectural Principles:

    • Testing Law: Every workstream must start with failing tests at the tier that can observe the behavior. Persistent behavior must be proven on both libSQL and PostgreSQL.
    • Composition: Stays assembly-only. New behavior must reside in its owning crates.
    • Dependency Rule: Generic crates must never depend on concrete extension crates. Only the canonical ironclaw CLI package and tests are permitted to link concrete extension crates.