diff --git a/.gitignore b/.gitignore index cf7638a941b..f0a733f2c1a 100644 --- a/.gitignore +++ b/.gitignore @@ -109,3 +109,6 @@ crates/*/frontend/dist/ # It is a regenerable build artifact of a local audit, never source. mutants.out/ mutants.out.old/ + +# for a local typescript app, but don't want to push with main repo +/app/ diff --git a/docs/capabilities/skills.mdx b/docs/capabilities/skills.mdx index 5ef86570b4f..28eb07cd9c2 100644 --- a/docs/capabilities/skills.mdx +++ b/docs/capabilities/skills.mdx @@ -6,44 +6,42 @@ description: Prompt extensions that activate based on context Skills are markdown files that contain domain-specific instructions. When a skill activates, its markdown body is injected into the LLM context — giving the agent specialized knowledge and behavior without retraining. -IronClaw can search and install skills from the ClawHub registry, a community-driven repository of pre-built skills covering various domains and use cases. +IronClaw can search and install skills from the IronHub registry, a community-driven repository of pre-built skills covering various domains and use cases. See [IronHub](/hub/overview) for the full catalog. --- -## What Skills Do +## What skills do A skill is a self-contained expertise module. It defines: - **When to activate** — patterns, keywords, and regex that match incoming messages - **What to inject** — a markdown body with instructions, examples, and domain knowledge -- **What tools to require** — binaries, environment variables, and configuration needed +- **What prerequisites to declare** — binaries, environment variables, and configuration needed - **How much context to use** — a token budget cap per activation Skills are evaluated on every turn. The agent selects the most relevant skills that fit within the prompt budget and injects them before the LLM reasons about the request. --- -## Activation Pipeline +## Activation pipeline Skills pass through four stages before injection: - Check that all prerequisites are met: required binaries exist on `PATH`, required environment variables are set, required configuration is present. Skills that fail gating are skipped entirely — they never score or consume budget. + Skills with `auto_activate = false` are excluded before scoring. Skills with `auto_activate = true` (the default) proceed to scoring. Explicit `$name` and `/name` mentions bypass this gate entirely — they activate regardless of the `auto_activate` flag. - Each gated skill is scored against the current message using a deterministic algorithm: keyword matches, tag overlaps, and regex pattern matches. Higher scores indicate stronger relevance. + Each skill is scored against the current message using a deterministic algorithm: keyword matches, tag overlaps, and regex pattern matches. Higher scores indicate stronger relevance. - Scoring is fully deterministic — no LLM involved. A skill must declare its activation criteria in the frontmatter so the scorer knows what to match. Legacy agent-loop selection can use this score to inject full skill context. + Scoring is fully deterministic — no LLM involved. A skill must declare its activation criteria in the frontmatter so the scorer knows what to match. - Set `SKILLS_REGEX_ACTIVATION_ENABLED=false` to disable regex pattern auto-activation. Keyword/tag activation and explicit skill mentions, such as `$my-skill`, still inject skills. - - Reborn local-dev uses Codex-style selection: `skill_list` exposes a compact catalog, natural-language keyword/tag/pattern matches do not inject full skill bodies, and full `SKILL.md` context is loaded only after an explicit `$skill` mention or a model-selected local-dev `skill_activate` call. + Set `regex_activation_enabled = false` under `[skills]` in your config to disable regex pattern auto-activation. Keyword/tag activation and explicit skill mentions, such as `$my-skill` or `/my-skill`, still inject skills. - A skill without an `activation` block scores zero on every message and is never injected. + A skill without any activation criteria (keywords, tags, or patterns) always scores zero during automatic selection, but can still be activated by explicit `$name` or `/name` mentions. ```yaml @@ -63,6 +61,11 @@ Skills pass through four stages before injection: exclude_keywords: - dry-run max_context_tokens: 2000 + requires: + bins: + - docker + env: + - DOCKER_HOST --- ``` @@ -72,31 +75,39 @@ Skills pass through four stages before injection: | `patterns` | Regex patterns. Each match adds significant weight — use for intent-specific phrases. | | `tags` | Short labels for broad domain matching (e.g. `blockchain`, `cli`). | | `exclude_keywords` | Veto list — if any appear in the message, the skill scores zero regardless of other matches. | - | `max_context_tokens` | Token budget this skill may consume per turn. Omitting it leaves the skill with a 2000-token budget, effectively excluding it. | + | `max_context_tokens` | Token budget this skill may consume per turn. Defaults to 2000 if omitted, a conservative cap that limits context usage. | + | `auto_activate` | Set to `false` to prevent keyword/regex auto-activation. The skill must be mentioned explicitly by name or loaded via `skill_activate`. | + | `setup_marker` | One-time setup marker. Excludes this skill from activation after it has been run once. Use for skills that perform initial configuration (e.g., setting up a repo connection). | + | `requires.bins` | Binaries that must exist on `PATH` for the skill to function. Parsed but not enforced during selection. | + | `requires.env` | Environment variables that must be set for the skill to function. Parsed but not enforced during selection. | If a skill appears in `ironclaw skills list` but the agent doesn't use it, the most common cause is a missing or empty `activation` block. + + Local-dev uses Codex-style selection: `skill_list` exposes a compact catalog, natural-language keyword/tag/pattern matches do not inject full skill bodies, and full `SKILL.md` context is loaded only after an explicit `$skill` mention or a model-selected `skill_activate` call. + + - Skills are sorted by score descending. Starting from the highest-scoring skill, each is selected until the `SKILLS_MAX_TOKENS` budget is exhausted. Lower-scoring skills that don't fit are dropped for this turn. + Skills are sorted by score descending. Starting from the highest-scoring skill, each is selected until the total token budget is exhausted. Lower-scoring skills that don't fit are dropped for this turn. - Trust-based tool ceiling is applied. Installed skills (from ClawHub) lose access to dangerous tools regardless of what the skill requests. Trusted skills retain full tool access. See Trust Levels below. + Trust-based restrictions are applied. Installed skills (from IronHub) are excluded from model-selected activation — the agent cannot load them via `skill_activate`. Skills in trusted directories retain full activation access. See Trust Levels below. --- -## Trust Levels +## Trust levels -| Trust Level | Source | Tool Access | -|---------------|-------------------------------------------------------------|---------------------------------------------------------| -| **Trusted** | User-placed in `~/.ironclaw/skills/` or workspace `skills/` | All tools available to the agent | -| **Installed** | Downloaded from ClawHub registry via `skill_install` | Read-only tools only — no shell, no file write, no HTTP | +| Trust Level | Source | Activation access | +|---------------|-------------------------------------------------------------|----------------------------------------------------------| +| **Trusted** | User-placed in `~/.ironclaw/skills/` or workspace `skills/` | Model can auto-select via `skill_activate` | +| **Installed** | Downloaded from IronHub registry via `ironclaw ironhub install --kind skill` | Excluded from `skill_activate`. Available via explicit `$name` mention. | Never place a skill file in the trusted directories unless you have reviewed its contents. A skill in `~/.ironclaw/skills/` has the same tool access as you do. @@ -104,7 +115,7 @@ Never place a skill file in the trusted directories unless you have reviewed its --- -## Skill Directories +## Skill directories IronClaw discovers skills from three locations, checked in order: @@ -112,9 +123,9 @@ IronClaw discovers skills from three locations, checked in order: |---------------------------------|-----------|-------------------------------------------------------------| | `~/.ironclaw/skills/` | Trusted | User's global skills, available in all sessions | | `/skills/` | Trusted | Per-workspace skills, activated in that workspace's context | -| `~/.ironclaw/installed_skills/` | Installed | Registry-installed skills from ClawHub | +| `~/.ironclaw/installed_skills/` | Installed | Registry-installed skills from IronHub | -Skills in trusted directories are loaded as-is. Skills in `installed_skills/` have their tool access capped by the attenuation layer regardless of what they declare. +Skills in trusted directories are loaded as-is. Skills in `installed_skills/` follow the same activation rules as the Trust levels table above. Each skill lives in its own subdirectory named after the skill: @@ -134,14 +145,6 @@ A correctly installed skill appears with its name, version, and trust level. If --- -## Auto-Discovery - -When `SKILLS_AUTO_DISCOVER=true` (the default), IronClaw scans all skill directories at startup and indexes all valid SKILL.md files. New skills added while the agent is running are picked up on the next restart. +## Auto-discovery -```bash -# Enable auto-discovery (default: true) -SKILLS_AUTO_DISCOVER=true - -# Max tokens injected per turn across all active skills -SKILLS_MAX_TOKENS=4000 -``` +IronClaw scans all skill directories at startup and indexes all valid SKILL.md files. New skills added while the agent is running are picked up on the next restart. diff --git a/docs/channels/building-a-channel.mdx b/docs/channels/building-a-channel.mdx index 40a007b468c..28d3f8a069b 100644 --- a/docs/channels/building-a-channel.mdx +++ b/docs/channels/building-a-channel.mdx @@ -25,22 +25,16 @@ cargo install wasm-tools ## 1. Create the project structure -Create a new crate outside the retired legacy source trees with this layout: +Create a new crate with this layout: ```text my-channel/ ├── Cargo.toml ├── src/ │ └── lib.rs -└── my-channel.capabilities.json -``` - -After building, deploy to: - -```text -~/.ironclaw/channels/ -├── my-channel.wasm -└── my-channel.capabilities.json +├── wasm/ +│ └── my-channel.wasm # built artifact +└── manifest.toml ``` --- @@ -58,7 +52,7 @@ description = "My messaging platform channel for IronClaw" crate-type = ["cdylib"] [dependencies] -wit-bindgen = "0.36" +wit-bindgen = "=0.36" serde = { version = "1", features = ["derive"] } serde_json = "1" @@ -73,7 +67,7 @@ codegen-units = 1 ## 3. Implement the channel interface -Now that the crate is ready, implement the channel guest interface exposed by `crates/ironclaw_wasm/wit/channel.wit`, and implement the guest trait methods to handle incoming messages and send responses. +Implement the channel guest interface from `wit/channel.wit`: ### Required Imports @@ -104,20 +98,23 @@ impl Guest for MyChannel { /// Called once when the channel starts. /// Returns configuration for webhooks and polling. fn on_start(config_json: String) -> Result { - // Parse config from capabilities file + // Parse config from config_json let config: MyConfig = serde_json::from_str(&config_json) .unwrap_or_default(); + // The manifest [channel.ingress] controls how the host routes inbound + // webhooks. The ChannelConfig here configures runtime registration with + // the platform API (e.g., registering a webhook URL with Telegram). Ok(ChannelConfig { display_name: "My Channel".to_string(), http_endpoints: vec![ HttpEndpointConfig { path: "/webhook/my-channel".to_string(), methods: vec!["POST".to_string()], - require_secret: true, // Validate webhook secret + require_secret: true, }, ], - poll: None, // Or Some(PollConfig { interval_ms, enabled }) + poll: None, }) } @@ -162,7 +159,7 @@ export!(MyChannel); -`on_start` configures how the host calls your channel. `on_http_request` and `on_poll` ingest external messages; `on_respond` delivers replies to an existing conversation; `on_broadcast` sends proactive messages; `on_status` lets channels surface thinking indicators and other progress updates. +`on_start` configures how the channel registers with its platform API. The manifest's `[channel.ingress]` controls how the host routes inbound webhooks — they are separate concerns. `on_http_request` and `on_poll` ingest external messages; `on_respond` delivers replies to an existing conversation; `on_broadcast` sends proactive messages; `on_status` lets channels surface thinking indicators and other progress updates. --- @@ -171,7 +168,7 @@ export!(MyChannel); Once your channel can receive messages, keep enough metadata to send responses back to the right chat and sender. -**The most important pattern**: Store routing info in message metadata so responses can be delivered. +Store routing info in message metadata so responses can be delivered to the right chat and sender. ```rust // When receiving a message, store routing info: @@ -185,7 +182,7 @@ struct MyMessageMetadata { // In on_http_request or on_poll: let metadata = MyMessageMetadata { chat_id: message.chat.id.clone(), - sender_id: message.from.clone(), // CRITICAL: Store sender! + sender_id: message.from.clone(), original_message_id: message.id.clone(), }; @@ -197,11 +194,9 @@ channel_host::emit_message(&EmittedMessage { metadata_json: serde_json::to_string(&metadata).unwrap_or_default(), }); -// In on_respond, use the ORIGINAL message's metadata: +// On respond, the stored sender_id becomes the recipient: fn on_respond(response: AgentResponse) -> Result<(), String> { let metadata: MyMessageMetadata = serde_json::from_str(&response.metadata_json)?; - - // sender_id becomes the recipient! send_message(metadata.chat_id, metadata.sender_id, response.content); } ``` @@ -217,7 +212,7 @@ fn on_respond(response: AgentResponse) -> Result<(), String> { Now that the message path is set, configure API credentials using placeholders instead of hardcoded tokens. -**Never hardcode credentials!** Use placeholders that the host replaces +Never hardcode credentials. Use placeholders that the host replaces. ### URL Placeholders (Telegram-style) @@ -225,7 +220,7 @@ Now that the message path is set, configure API credentials using placeholders i ```rust // The host replaces {TELEGRAM_BOT_TOKEN} with the actual token let url = "https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/sendMessage"; -channel_host::http_request("POST", url, &headers_json, Some(&body)); +channel_host::http_request("POST", url, &headers_json, Some(&body), None); ``` ### Header Placeholders (WhatsApp-style) @@ -235,141 +230,137 @@ let headers = serde_json::json!({ "Content-Type": "application/json", "Authorization": "Bearer {WHATSAPP_ACCESS_TOKEN}" }); -channel_host::http_request("POST", &url, &headers.to_string(), Some(&body)); +channel_host::http_request("POST", &url, &headers.to_string(), Some(&body), None); ``` The placeholder format is `{SECRET_NAME}` where `SECRET_NAME` matches the credential name in uppercase with underscores (e.g., `whatsapp_access_token` → `{WHATSAPP_ACCESS_TOKEN}`). --- -## 6. Define capabilities - -The capabilities file declares setup prompts, allowlists, and rate limits. - -```json my-channel.capabilities.json -{ - "type": "channel", - "name": "my-channel", - "description": "My messaging platform channel", - "setup": { - "required_secrets": [ - { - "name": "my_channel_api_token", - "prompt": "Enter your API token", - "validation": "^[A-Za-z0-9_-]+$" - }, - { - "name": "my_channel_webhook_secret", - "prompt": "Webhook secret (leave empty to auto-generate)", - "optional": true, - "auto_generate": { "length": 32 } - } - ], - "validation_endpoint": "https://api.my-platform.com/verify?token={my_channel_api_token}" - }, - "capabilities": { - "http": { - "allowlist": [ - { "host": "api.my-platform.com", "path_prefix": "/" } - ], - "rate_limit": { - "requests_per_minute": 60, - "requests_per_hour": 1000 - } - }, - "secrets": { - "allowed_names": ["my_channel_*"] - }, - "channel": { - "allowed_paths": ["/webhook/my-channel"], - "allow_polling": false, - "workspace_prefix": "channels/my-channel/", - "emit_rate_limit": { - "messages_per_minute": 100, - "messages_per_hour": 5000 - }, - "webhook": { - "secret_header": "X-Webhook-Secret", - "secret_name": "my_channel_webhook_secret" - } - } - }, - "config": { - "custom_option": "value" - } -} +## 6. Create the extension manifest + +Channels are installed as extensions. The manifest declares the runtime surface and channel configuration in TOML format: + +```toml my-channel/manifest.toml +schema_version = "reborn.extension_manifest.v3" +id = "my-channel" +name = "My Channel" +version = "0.1.0" +description = "My messaging platform channel for IronClaw" +trust = "third_party" + +[runtime] +kind = "wasm" +module = "wasm/my_channel.wasm" + +[admin_configuration] +group_id = "extension.my-channel" +display_name = "My Channel deployment configuration" +fields = [ + { handle = "my_channel_api_token", label = "API token", secret = true, required = true }, + { handle = "my_channel_webhook_secret", label = "Webhook secret", secret = true, required = true }, +] + +[channel] +id = "messages" +display_name = "My Channel messages" +inbound = true +outbound = true +conversation_model = "continuous" + +[channel.ingress] +route_suffix = "webhook" +method = "post" +body_limit_bytes = 1048576 + +[channel.ingress.verification] +kind = "shared_secret_header" +secret_handle = "my_channel_webhook_secret" +header = "X-Webhook-Secret" + +[[channel.egress]] +scheme = "https" +host = "api.my-platform.com" +methods = ["post"] +credential_handle = "my_channel_api_token" +paths = ["/send"] +injection = { type = "header", name = "authorization", prefix = "Bearer " } + +[channel.presentation] +supports_markdown = false +supports_threads = false +max_message_chars = 4096 +``` + +Place the manifest alongside the WASM binary with this layout: + +```text +my-channel/ +├── Cargo.toml +├── src/ +│ └── lib.rs +├── wasm/ +│ └── my_channel.wasm +└── manifest.toml ``` --- ## 7. Build and install -With code and capabilities in place, build the channel and copy the two required artifacts. - -### Generic channel build +Build the WASM component and place it in the extension asset directory alongside the manifest. ```bash cd my-channel cargo build --release --target wasm32-wasip2 # Convert the raw wasm module into a component and strip it -wasm-tools component new target/wasm32-wasip2/release/my_channel.wasm -o my-channel.wasm \ - 2>/dev/null || cp target/wasm32-wasip2/release/my_channel.wasm my-channel.wasm -wasm-tools strip my-channel.wasm -o my-channel.wasm - -mkdir -p ~/.ironclaw/channels -cp my-channel.wasm ~/.ironclaw/channels/my-channel.wasm -cp my-channel.capabilities.json ~/.ironclaw/channels/ -``` - - -Current first-party channels are shipped as packaged artifacts. For repository-maintained Reborn channels, use `crates/extensions/packages//manifest.toml` plus checked-in schemas/prompts and CI-built WASM artifacts rather than adding a new legacy source tree. - - -### Packaged channel artifact example - -```bash -mkdir -p ~/.ironclaw/channels -cp my-channel.wasm my-channel.capabilities.json ~/.ironclaw/channels/ +wasm-tools component new target/wasm32-wasip2/release/my_channel.wasm -o wasm/my_channel.wasm \ + 2>/dev/null || cp target/wasm32-wasip2/release/my_channel.wasm wasm/my_channel.wasm +wasm-tools strip wasm/my_channel.wasm -o wasm/my_channel.wasm ``` - -If you are contributing a channel to the public repository, **do not commit compiled WASM binaries.** They are a supply chain risk — the binary in a PR may not match the source. IronClaw builds channels from source. - +The extension is installed through the IronClaw extension lifecycle. For host-bundled channels, add the manifest and WASM to `crates/ironclaw_first_party_extensions/assets//` and register it in `crates/ironclaw_extension_host/src/available_extensions.rs`. For local development, place the extension directory under `/local-dev/system/extensions//`. --- ## 8. Host functions you can call -Channel modules get a small host API for logging, storage, HTTP, and message emission: +### Core APIs (every channel uses these) ```rust +// Logging and time channel_host::log(channel_host::LogLevel::Info, "message"); - let _now = channel_host::now_millis(); +// Durable per-channel workspace key-value storage let _ = channel_host::workspace_write("state/offset", "12345"); let _ = channel_host::workspace_read("state/offset"); -let _response = channel_host::http_request("POST", &url, &headers, Some(&body)); +// Make outbound HTTP requests to the messaging platform API +let _response = channel_host::http_request("POST", &url, &headers, Some(&body), None); +// Emit an inbound message to the agent channel_host::emit_message(&EmittedMessage { /* ... */ }); + +// Check whether a deployment secret exists +let has_secret = channel_host::secret_exists("telegram_bot_token"); ``` -Real channels also use a few additional host APIs: +### Advanced APIs (pairing, attachments) -```rust -let has_secret = channel_host::secret_exists("telegram_bot_token"); +Channels that download binary payloads (voice notes, images) or support owner approval for unknown senders can use these: +```rust +// Store binary attachment data received during a webhook or poll callback let _ = channel_host::store_attachment_data("attachment-id", &bytes); +// Pairing: create a code for a user to prove ownership of a platform account let _ = channel_host::pairing_upsert_request("telegram", "123456", "{}")?; let _ = channel_host::pairing_resolve_identity("telegram", "123456")?; let _ = channel_host::pairing_read_allow_from("telegram")?; ``` -Use `store_attachment_data` when you download binary payloads such as voice notes or images during webhook or polling callbacks. Use the pairing APIs when your channel supports owner approval for unknown direct-message senders. - --- ## 9. Common patterns @@ -420,7 +411,7 @@ if sender.is_bot { ## 10. Testing and troubleshooting -Add basic parsing and metadata round-trip tests: +Add tests for message parsing and metadata round-trips. The key assertions are that routing metadata is preserved through serialization: ```rust #[cfg(test)] @@ -428,10 +419,24 @@ mod tests { use super::*; #[test] - fn test_parse_webhook() { - let json = r#"{\"messages\":[]}"#; - let v: serde_json::Value = serde_json::from_str(json).expect("valid json in test"); - assert!(v.get("messages").is_some()); + fn test_metadata_round_trip() { + let metadata = MyMessageMetadata { + chat_id: "123".into(), + sender_id: "user_456".into(), + original_message_id: "msg_789".into(), + }; + let serialized = serde_json::to_string(&metadata).expect("serialize"); + let deserialized: MyMessageMetadata = + serde_json::from_str(&serialized).expect("deserialize"); + assert_eq!(deserialized.chat_id, "123"); + assert_eq!(deserialized.sender_id, "user_456"); + } + + #[test] + fn test_rejects_missing_fields() { + let json = r#"{"chat_id":"123"}"#; + let result: Result = serde_json::from_str(json); + assert!(result.is_err()); } } ``` @@ -444,6 +449,6 @@ let preview: String = content.chars().take(50).collect(); If credential placeholders are not resolved: -1. Verify secret names match the declared placeholders. -2. Confirm the secret is permitted in `allowed_names`. +1. Verify secret names match the declared placeholders in the manifest. +2. Confirm the credential handle matches what the channel code expects. 3. Check runtime logs for unresolved placeholder warnings. diff --git a/docs/docs.json b/docs/docs.json index 9cc9c3e49f1..1aef4e2e9fb 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -100,6 +100,15 @@ "channels/telegram" ] }, + { + "group": "IronHub", + "icon": "archive", + "pages": [ + "hub/overview", + "hub/installing", + "hub/contributing" + ] + }, { "group": "API", "icon": "code", diff --git a/docs/extensions/building-a-tool.md b/docs/extensions/building-a-tool.md index f5b0fa9c293..9ca5df8244d 100644 --- a/docs/extensions/building-a-tool.md +++ b/docs/extensions/building-a-tool.md @@ -1,14 +1,11 @@ --- -title: How to implement a Reborn tool extension -description: "A Reborn-only implementation guide for IronClaw extension tools" +title: How to implement a tool extension +description: "An implementation guide for IronClaw extension tools" --- -# How to implement a Reborn tool extension +# How to implement a tool extension -This guide is for coding agents and engineers adding an IronClaw Reborn -extension tool. It is intentionally Reborn-only. Do not use V1 extension, -native-extension, pending-OAuth-map, or legacy tool-router patterns when -following this document. +This guide is for coding agents and engineers adding an IronClaw tool extension. The guide is grounded in the current GitHub, GSuite, and Notion implementations: @@ -17,36 +14,37 @@ The guide is grounded in the current GitHub, GSuite, and Notion implementations: - GSuite: bundled WASM capability providers for Gmail, Calendar, Docs, Drive, Sheets, and Slides. - Notion: bundled hosted HTTP MCP capability provider under - `crates/extensions/packages/notion-mcp/`, with product - auth / OAuth DCR wiring in Reborn composition. + `crates/ironclaw_first_party_extensions/assets/notion-mcp/`, with product + auth / OAuth DCR wiring in composition. ## Success criteria -A Reborn tool extension is complete only when all of the following are true: +A tool extension is complete only when all of the following are true: -1. The extension package has a `schema_version = "reborn.extension_manifest.v2"` +1. The extension package has a `schema_version = "reborn.extension_manifest.v3"` (or v2 for legacy manifests) manifest and every model-visible capability has schema, output schema, and prompt assets. 2. The manifest declares the correct runtime lane: `wasm`, `mcp`, or `script`. -3. The manifest exposes tools through `ironclaw.capability_provider/v1` via the - registry extension manifest path. Do not add or copy top-level - `[[capabilities]]` declarations. +3. (v3) Tools are declared with `[[tools]]` and inline `[[tools.credentials]]`. + (v2 legacy) Tools are exposed through `ironclaw.capability_provider/v1` via the + registry `[[host_api]]` path. Do not add or copy top-level + `[[capabilities]]` declarations in either version. 4. The runtime code does not read raw secrets, create its own HTTP client for external provider calls, bypass approvals, or dispatch directly into the agent loop. 5. Network, credentials, approvals, and resource bounds are enforced by the - Reborn host APIs and runtime services. + host APIs and runtime services. 6. Tests cover manifest validation, runtime dispatch behavior, credential/auth gates, and caller-facing behavior through the runtime or lifecycle call site. -## Reborn extension flow +## Extension flow Use this mental model before touching files: ```text Extension package -> lifecycle/discovery materializes it into the extension registry - -> ironclaw_extensions parses manifest v2 host APIs and projects descriptors + -> ironclaw_extensions parses manifest surfaces and projects descriptors -> ironclaw_host_runtime publishes hot model-facing schemas/prompts -> model selects a visible capability -> ironclaw_capabilities performs authorization, approvals, obligations, run state @@ -73,10 +71,10 @@ Pick one lane first. Do not blend lanes to make a tool work. | Lane | Use when | Current examples | Main files | | --- | --- | --- | --- | -| WASM capability provider | Provider logic can run in a sandboxed component and use host HTTP egress. This is the default for provider tools. | GitHub, Gmail, Google Calendar, Google Drive, Google Docs, Google Sheets, Google Slides | `crates/extensions/packages//manifest.toml`, `schemas/`, `prompts/`, optional `wasm-src/` | -| Hosted HTTP MCP | The provider already exposes an MCP server and the host should lock egress to that endpoint. | Notion hosted MCP | `assets/-mcp/manifest.toml`, schemas/prompts, `crates/ironclaw_reborn_composition/src/mcp.rs` only if adding a new host-bundled MCP policy shape | -| Product adapter | The extension receives external inbound events or product webhooks. This is not just a model-callable tool lane. | Slack/Telegram-style adapters, not the main focus of this guide | `crates/ironclaw_product_adapters`, `crates/ironclaw_product_adapter_registry`, `crates/ironclaw_wasm_product_adapters` | -| Script | Sandboxed process/CLI capability. Use only when a process boundary is the product requirement. | Project tools / CLI-style tools | `crates/ironclaw_sandbox` script runtime path plus manifest runtime `script` | +| WASM capability provider | Provider logic can run in a sandboxed component and use host HTTP egress. This is the default for provider tools. | GitHub, Gmail, Google Calendar, Google Drive, Google Docs, Google Sheets, Google Slides | `crates/ironclaw_first_party_extensions/assets//manifest.toml`, `schemas/`, `prompts/`, optional `wasm-src/` | +| Hosted HTTP MCP | The provider already exposes an MCP server and the host should lock egress to that endpoint. | Notion hosted MCP | `assets/-mcp/manifest.toml`, schemas/prompts, `crates/ironclaw_extension_host/src/mcp.rs` only if adding a new host-bundled MCP policy shape | +| Product adapter | The extension receives external inbound events or product webhooks. This is not just a model-callable tool lane. | Slack/Telegram-style adapters, not the main focus of this guide | `crates/ironclaw_product/src/adapter_registry.rs` | +| Script | Sandboxed process/CLI capability. Use only when a process boundary is the product requirement. | Project tools / CLI-style tools | `crates/ironclaw_scripts` runtime path plus manifest runtime `script` | For a new provider API like Linear, Jira, or a small internal SaaS API, start with WASM unless you have a concrete reason not to. @@ -89,16 +87,16 @@ Touch only the smallest set for your lane. Usually touch: -- `crates/extensions/packages//manifest.toml` -- `crates/extensions/packages//schemas//*.json` -- `crates/extensions/packages//prompts//*.md` -- `crates/ironclaw_reborn_composition/src/available_extensions.rs` only when adding +- `crates/ironclaw_first_party_extensions/assets//manifest.toml` +- `crates/ironclaw_first_party_extensions/assets//schemas//*.json` +- `crates/ironclaw_first_party_extensions/assets//prompts//*.md` +- `crates/ironclaw_extension_host/src/available_extensions.rs` only when adding a host-bundled available extension to the built-in install catalog. Do not touch for ordinary tools: -- `crates/ironclaw_extensions/src/v2.rs`, unless changing the manifest contract - itself. +- `crates/ironclaw_extensions/src/v2.rs` or `src/v3.rs`, unless changing the + manifest contract itself. - `crates/ironclaw_host_api/src/*`, unless adding a new shared host API type. - `crates/ironclaw_capabilities`, unless changing authorization/approval orchestration for all capabilities. @@ -117,7 +115,7 @@ Usually touch: - `crates/extensions/packages//wasm-src/` - `crates/extensions/packages//wasm/.wasm` - the extension manifest, schemas, and prompts. -- `crates/ironclaw_reborn_composition/src/available_extensions.rs` to package +- `crates/ironclaw_extension_host/src/available_extensions.rs` to package the manifest, schemas, prompts, and WASM bytes if host-bundled. Use as references: @@ -127,7 +125,7 @@ Use as references: - `crates/ironclaw_host_runtime/src/wasm_credentials.rs` Do not add a direct `reqwest`/HTTP client inside the WASM tool. Use the WIT host -HTTP import (`near::agent::host::http_request`) so Reborn can enforce egress, +HTTP import (`near::agent::host::http_request`) so the runtime can enforce egress, inject staged credentials, and sanitize failures. ### Hosted MCP lane @@ -137,17 +135,17 @@ Usually touch: - `crates/extensions/packages/-mcp/manifest.toml` - `schemas//...` - `prompts//...` -- `crates/ironclaw_reborn_composition/src/available_extensions.rs` if +- `crates/ironclaw_extension_host/src/available_extensions.rs` if host-bundled. Use as references: -- `crates/extensions/packages/notion-mcp/manifest.toml` -- `crates/ironclaw_reborn_composition/src/mcp.rs` +- `crates/ironclaw_first_party_extensions/assets/notion-mcp/manifest.toml` +- `crates/ironclaw_extension_host/src/mcp.rs` - `crates/ironclaw_auth/src/engine/` - composition provider wiring in `crates/ironclaw_reborn_composition/src/factory.rs` -Only touch `crates/ironclaw_reborn_composition/src/mcp.rs` if the hosted MCP +Only touch `crates/ironclaw_extension_host/src/mcp.rs` if the hosted MCP runtime policy needs a new generic rule. Notion already demonstrates the common shape: HTTPS-only endpoint, exact host/path match, no URL credentials, no query, no fragment, host-mediated egress, staged product-auth token. @@ -169,42 +167,65 @@ Usually touch only when adding a new product-auth provider: Do not create extension-local OAuth maps or store OAuth tokens in runtime code. Credential accounts and secrets belong to `ironclaw_auth` / -`ironclaw_secrets` through Reborn composition. +`ironclaw_secrets` through composition. ## Files not to touch -For a normal extension, do not touch these: +For a tool extension, do not touch these: -- `src/agent/*` or Reborn loop strategy code to special-case your tool. +- `src/agent/*` or loop strategy code to special-case your tool. - `crates/ironclaw_llm/*` to teach the model your tool name. -- `crates/ironclaw_engine/*` V1 runtime paths. -- `src/tools/*` V1 tools. - `crates/ironclaw_host_api` for one provider's fields. -- `crates/ironclaw_extensions/src/v2.rs` to allow a one-off manifest shortcut. +- `crates/ironclaw_extensions/src/v2.rs` or `src/v3.rs` to allow a one-off manifest shortcut. - `crates/ironclaw_network` to allow one provider host. - `crates/ironclaw_secrets` to fetch one provider token. - `crates/ironclaw_approvals` to make one write operation easier. If your implementation appears to require one of these, stop and identify the -missing Reborn contract or composition seam first. +missing contract or composition seam first. + +## Manifest structure -## Manifest v2 structure +The current schema is `reborn.extension_manifest.v3`. v2 is also supported and parses through the same entry point, but new extensions should use v3. -All Reborn packages use: +v3 drops the `[[host_api]]` indirection in favor of first-class surface declarations. A tool extension uses: ```toml -schema_version = "reborn.extension_manifest.v2" +schema_version = "reborn.extension_manifest.v3" id = "example" name = "Example" version = "0.1.0" -description = "Example tools for Reborn." +description = "Example tools for IronClaw." trust = "third_party" [runtime] kind = "wasm" module = "wasm/example_tool.wasm" + +[[tools]] +id = "example.search" +description = "Search Example records." +effects = ["network", "use_secret"] +default_permission = "ask" +visibility = "model" +input_schema_ref = "schemas/example/search.input.v1.json" +output_schema_ref = "schemas/example/search.output.v1.json" +prompt_doc_ref = "prompts/example/search.md" + +[[tools.credentials]] +handle = "example_runtime_token" +vendor = "example" +audience = { scheme = "https", host = "api.example.com" } +injection = { type = "header", name = "authorization", prefix = "Bearer " } ``` +v3 surfaces are declared at the top level: +- `[[tools]]` — model-callable tools with inline credentials +- `[channel]` — at most one channel surface per extension +- `[mcp]` — hosted MCP server (mutually exclusive with `[channel]`) +- `[memory]` — memory provider surface +- `[auth.]` — OAuth/API-key auth recipes + Extension IDs and capability IDs are authority-bearing: - `id` must be lowercase ASCII letters/digits plus `_`, `-`, or `.`. @@ -213,9 +234,9 @@ Extension IDs and capability IDs are authority-bearing: - Registry extensions cannot claim effective first-party/system authority. Host composition decides effective trust. -### All tool extensions: use `host_api` +### v2 compatibility: `host_api` (legacy) -Publish model-visible tools via the capability-provider host API: +v2 uses the capability-provider host API indirection. An equivalent v2 declaration looks like: ```toml [[host_api]] @@ -239,14 +260,13 @@ runtime_credentials = [ ] ``` -Do not use top-level `[[capabilities]]` for Reborn tool work. If a current +Do not use top-level `[[capabilities]]` for tool work. If a current bundled manifest still has that shape, do not treat that file shape as a -reference. Treat it as migration debt and move it to `[[host_api]]` plus -`[capability_provider.tools]` when touching that extension. +reference. Treat it as migration debt. -### Capability fields +### Capability fields (v3) -Required per model-visible capability: +Required per model-visible tool capability in v3: - `id`: stable `.` capability ID. - `description`: short, model-facing description. @@ -258,17 +278,17 @@ Required per model-visible capability: - `input_schema_ref`: relative path to JSON schema. - `output_schema_ref`: relative path to JSON schema. - `prompt_doc_ref`: relative path to concise operation guidance. -- `required_host_ports`: include `host.runtime.http_egress` when the runtime - must make host-mediated HTTP calls. -- `runtime_credentials`: declare every credential the runtime may receive. +- `credentials`: per-tool credential declarations (see below). + +In v2, credentials are declared at the capability level with +`runtime_credentials` and network egress uses `required_host_ports`. In v3, +credentials are inline per tool with `[[tools.credentials]]` and host ports are +implied by the credential's audience. Validation catches common mistakes: -- `runtime_credentials` without `use_secret` is rejected. This includes - product-auth account credentials: product auth selects/refreshes the account, - but runtime dispatch still uses a host-staged access-secret handle. +- Credentials without `use_secret` in `effects` are rejected. - Duplicate effects and duplicate credential handles are rejected. -- Unknown host ports are rejected. - Credential audiences must be declared as HTTPS. - Schema and prompt refs must be relative package paths, not absolute paths, URLs, backslash paths, or paths with `..`. @@ -344,7 +364,7 @@ Network policy belongs in host/runtime planning: - WASM credential injection is derived from manifest descriptors in `crates/ironclaw_host_runtime/src/wasm_credentials.rs`. - Hosted MCP policy is planned in - `crates/ironclaw_reborn_composition/src/mcp.rs`. + `crates/ironclaw_extension_host/src/mcp.rs`. - GSuite WASM tools should declare narrow credential audiences and use host HTTP egress for Google API hosts. - Shared HTTP enforcement and redaction live in @@ -352,44 +372,46 @@ Network policy belongs in host/runtime planning: Provider requests should set ordinary provider headers like `Accept`, `Content-Type`, API version, and User-Agent in runtime code. Credential headers -must come from `runtime_credentials` and host egress injection. +must come from the credential declaration and host egress injection. -## Secrets and runtime credentials +## Credentials and secrets Secrets are opaque handles in manifests and host API types. Runtime code should never see raw token material except as already-injected HTTP request data inside the host egress boundary. -Use `runtime_credentials` for every credential. Product auth is the preferred -source for provider accounts, but it is still represented as a runtime -credential because host egress injects the selected account's access-secret -handle at dispatch time: +In v3, credentials are declared inline per tool with `[[tools.credentials]]`: ```toml -runtime_credentials = [ - { handle = "github_runtime_token", source = { type = "product_auth_account", provider = "github" }, audience = { scheme = "https", host_pattern = "api.github.com" }, target = { type = "header", name = "authorization", prefix = "Bearer " } }, -] +[[tools.credentials]] +handle = "github_runtime_token" +vendor = "github" +audience = { scheme = "https", host = "api.github.com" } +injection = { type = "header", name = "authorization", prefix = "Bearer " } ``` -Important fields: +In v2, credentials use the `runtime_credentials` field at the capability level. + +Important fields (v3): - `handle`: extension/runtime-local credential handle. Keep it stable. -- `source`: omit or use `{ type = "secret_handle" }` only for manual direct - secret-handle credentials. Prefer `{ type = "product_auth_account", ... }` - for OAuth/account-backed integrations. -- `source.provider`: provider account namespace, for example `github`, - `google`, or `notion`. -- `source.setup`: `manual_token` or `oauth` with scopes. -- `provider_scopes`: scopes required for this capability. Use this for account - selection and scope mismatch checks. -- `audience`: exact HTTPS provider host pattern the credential may be sent to. -- `target`: header/query/path-placeholder injection target. Header is preferred. +- `vendor`: provider account namespace, for example `github`, `google`, or + `notion`. Must have a matching `[auth.]` recipe in the manifest. +- `scopes`: scopes required for this capability. Used for account selection + and scope mismatch checks. +- `audience`: exact HTTPS provider host the credential may be sent to. +- `injection`: header/query/path-placeholder injection target. Header is + preferred. - `required`: defaults to `true`. +In v2, the equivalent fields are `source`, `provider_scopes`, `audience` with +`host_pattern`, and `target`. + Credential flow: ```text -manifest runtime_credentials +[[tools.credentials]] + -> auth.vendor recipe provides OAuth/API-key setup -> authorization obligation for use_secret -> product-auth account selection or secret lease -> RuntimeSecretInjectionStore staging @@ -460,7 +482,7 @@ impl exports::near::agent::tool::Guest for ExampleTool { } fn description() -> String { - "Example Reborn tool. Credentials are injected only by host HTTP egress.".to_string() + "Example tool. Credentials are injected only by host HTTP egress.".to_string() } } @@ -499,7 +521,7 @@ transport = "http" url = "https://mcp.notion.com/mcp" ``` -For host-bundled hosted HTTP MCP, Reborn composition: +For host-bundled hosted HTTP MCP, composition: - accepts only HTTPS endpoint URLs; - rejects userinfo, query strings, fragments, wrong scheme, wrong host, and @@ -520,7 +542,7 @@ agent-loop path. Let the MCP runtime and host egress planner own it. Host-bundled extension packages are included in: -- `crates/ironclaw_reborn_composition/src/available_extensions.rs` +- `crates/ironclaw_extension_host/src/available_extensions.rs` That file: @@ -599,23 +621,24 @@ errors into model output. ## Tests to add -Minimum tests for a Reborn tool: +Minimum tests for a tool: ### Manifest and packaging -- manifest parses as `reborn.extension_manifest.v2`; +- manifest parses as `reborn.extension_manifest.v3` (or v2 for legacy manifests); - capability IDs use the extension prefix; - every capability has matching schema and prompt assets; - credential capabilities include `use_secret`; - write capabilities include `external_write` and default to `ask`; - bundled package assets include every manifest ref; -- extension manifests use `[[host_api]]` / `[capability_provider.tools]`, never +- extension manifests use `[[tools]]` (v3) or `[[host_api]]` / `[capability_provider.tools]` (v2 legacy), never top-level `[[capabilities]]`. Useful existing test areas: - `crates/ironclaw_extensions/tests/manifest_v2_contract.rs` -- `crates/ironclaw_reborn_composition/src/available_extensions.rs` tests +- `crates/ironclaw_extensions/tests/manifest_v3_contract.rs` +- `crates/ironclaw_extension_host/src/available_extensions.rs` tests - `crates/ironclaw_host_runtime/src/capability_catalog.rs` tests ### Runtime behavior @@ -666,8 +689,8 @@ Before opening a PR, verify: Copy these runtime, credential, and security patterns, not legacy manifest shape. If one of these manifests still uses top-level `[[capabilities]]`, port -the semantics into the registry `[[host_api]]` / `[capability_provider.tools]` -shape before extending it. +the semantics to v3 `[[tools]]` (or v2 `[[host_api]]` / `[capability_provider.tools]` +for legacy extensions) before extending it. - GitHub WASM operation dispatch: `crates/extensions/packages/github/wasm-src/src/lib.rs` @@ -682,7 +705,7 @@ shape before extending it. - Notion hosted MCP credential/effect semantics: `crates/extensions/packages/notion-mcp/manifest.toml` - Hosted MCP egress planner: - `crates/ironclaw_reborn_composition/src/mcp.rs` + `crates/ironclaw_extension_host/src/mcp.rs` - Notion OAuth provider wiring: `crates/ironclaw_reborn_composition/src/factory.rs` - Hot capability catalog: @@ -696,8 +719,9 @@ shape before extending it. 1. Pick lane: WASM, hosted MCP, script, or product adapter. 2. Create package assets under `assets//`. -3. Write manifest v2 with the capability-provider host API and make it flow - through extension registry discovery/publication. +3. Write manifest v3 with `[[tools]]` and inline `[[tools.credentials]]` (or v2 + `[[host_api]]` for legacy manifests) and make it flow through extension + registry discovery/publication. 4. Add schemas and prompt docs for every model-visible capability. 5. Implement runtime code using host services only. 6. Declare credentials with narrow HTTPS audiences and provider scopes. diff --git a/docs/hub/contributing.mdx b/docs/hub/contributing.mdx new file mode 100644 index 00000000000..6dd093980ff --- /dev/null +++ b/docs/hub/contributing.mdx @@ -0,0 +1,27 @@ +--- +title: "Contributing" +description: "Submit your own skills and tools to the IronHub catalog" +--- + +Anyone can submit tools and skills to IronHub. Visit the developer portal for the full publishing guide, submission requirements, and review process: + + + hub.ironclaw.com/developer + + +--- + +## Provenance + +New submissions enter as **New** (unverified). After review they may move to **Verified** or **Trusted**. Only packages maintained by the IronClaw team are marked **Official**. See [Provenance tiers](/hub/overview#provenance-tiers) for how each tier is defined. + +--- + +## Before you submit + +You can publish two kinds of packages: **Tools** (WASM binary + capability manifest) and **Skills** (SKILL.md). + +- Follow the [Build a Tool](/extensions/building-a-tool) guide if you're creating a WASM extension. +- Follow the [Skills](/capabilities/skills) reference for SKILL.md format and activation patterns. +- Test your package locally before submitting. +- Keep your description clear — it's how users and agents discover your work in the catalog. diff --git a/docs/hub/installing.mdx b/docs/hub/installing.mdx new file mode 100644 index 00000000000..708466ba687 --- /dev/null +++ b/docs/hub/installing.mdx @@ -0,0 +1,100 @@ +--- +title: "Installing skills & tools" +description: "Install skills and tools from the IronHub catalog" +--- + +Packages from IronHub can be installed through the CLI or by asking your agent in chat. + +--- + +## CLI + +### Search + +Filter the catalog by keyword: + +```bash +ironclaw ironhub search github +``` + +### List + +Browse all entries, optionally filtered by kind: + +```bash +# All entries +ironclaw ironhub list + +# Tools only +ironclaw ironhub list --kind tool + +# Skills only +ironclaw ironhub list --kind skill +``` + +### Inspect an entry + +```bash +ironclaw ironhub info --kind tool +ironclaw ironhub info --kind skill +``` + +Prints the entry's provenance, version, and SHA-256 artifact digest. Use the digest to pin an exact version during install. + +### Install + +```bash +ironclaw ironhub install --kind tool +ironclaw ironhub install --kind skill +``` + + +Community entries (provenance `New`) require explicit acknowledgement from the operator. The agent cannot install them autonomously. + + +#### Pin to a version or digest + +By default IronClaw installs the version in the current manifest. To require a specific version or digest: + +```bash +ironclaw ironhub install --kind tool --expected-version "1.2.3" +ironclaw ironhub install --kind skill --expected-artifact-digest "sha256:abc123..." +``` + +#### Force reinstall + +```bash +ironclaw ironhub install --kind tool --force +``` + +--- + +## Via chat + +Ask your agent to search IronHub, inspect an entry, or install a package. It will fetch the catalog, present matching results, and ask your approval before installing anything. + +--- + +## Where things are installed + +| Package | Destination | +|---------|---------------------------------------------------| +| Skills | `~/.ironclaw/installed_skills//` | +| Tools | Active as an agent tool immediately after install | + +--- + +## Trust and tool access + +Packages installed from IronHub are **attenuated** — they have reduced tool access compared to packages you place directly in your skills directory: + +| Source | Trust | Tool access | +|-----------------------------------------------|-----------|---------------------------------------------------| +| `~/.ironclaw/skills/` or workspace `skills/` | Trusted | Full — same access as the agent | +| IronHub install | Installed | Read-only — no shell, no file write, no HTTP | + +If you fully trust an IronHub skill, move it to `~/.ironclaw/skills/` after reviewing its contents. + + +Never move a skill you haven't reviewed into the trusted directory. A skill in `~/.ironclaw/skills/` has the same execution power as you do. + diff --git a/docs/hub/overview.mdx b/docs/hub/overview.mdx new file mode 100644 index 00000000000..47cb81a75dc --- /dev/null +++ b/docs/hub/overview.mdx @@ -0,0 +1,54 @@ +--- +title: "Overview" +description: "The official catalog of installable tools and skills" +--- + +IronHub is the catalog of tools and skills for IronClaw, hosted at [hub.ironclaw.com](https://hub.ironclaw.com). Every entry is cryptographically signed — IronClaw verifies the signature before installation so you know exactly what you're installing and who published it. + + + + Browse the catalog of available tools and skills. + + + + See what others are building with IronClaw extensions. + + + +--- + +## What's in the catalog + +IronHub distributes two kinds of packages: + +| Kind | What it is | What you get | +|----------------|------------------------------------------|-----------------------------------------------| +| Extension (Tool) | WASM binary + capability manifest (TOML, `manifest.toml`) | A new tool your agent can call at runtime | +| Skill | SKILL.md | Prompt instructions the agent loads on demand | + +--- + +## Provenance tiers + +Every catalog entry carries a provenance label that tells you how it was reviewed: + +| Tier | Description | +|---------------|-------------------------------------------------------------------------------------------------------------------------------------------| +| **Official** | Published and maintained by the IronClaw team. | +| **Trusted** | Reviewed by the IronClaw team for safety and correctness. | +| **Verified** | Publisher identity is confirmed, but the package has not been audited. | +| **New** | Community submission with no review yet. Requires explicit operator acknowledgement to install — the agent cannot install these autonomously. | + +--- + +## Next steps + + + + Install packages via CLI or chat. + + + + Publish your own tool or skill to IronHub. + + diff --git a/docs/index.mdx b/docs/index.mdx index 94293ff4062..dfd9754b275 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -6,9 +6,7 @@ icon: "book" IronClaw is a secure, open-source AI agent framework built in Rust and deployed on NEAR AI Cloud. It enables creating AI agents with access to your tools and services, while keeping your credentials safe and private. -It ships as a single binary. After setup, `ironclaw serve` runs a web interface on your -machine where you chat with the agent, manage projects and jobs, connect channels, and -change settings. +The fastest way to get started is the [Agent Hub](https://agent.near.ai) — sign in, spin up a private instance, and chat with your agent immediately. For local deployment, IronClaw ships as a single binary that runs a web interface on your machine where you chat with the agent, manage projects and jobs, connect channels, and change settings. Deploy your first agent in minutes. @@ -44,17 +42,16 @@ change settings. -## Resources +## Get started - - Deploy your first agent in minutes. + + Spin up a private instance in minutes — no installation needed. - - - Manage your agents in one place. - - - The secure cloud platform for AI agents. - - + + Run IronClaw on your own machine with the single binary. + + + + Discover and install tools and skills from the signed catalog. + diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index 4b3c3bc6da6..aabcb1f482e 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -4,66 +4,83 @@ description: Create your first Agent in minutes icon: rocket --- -This guide will get you from zero to a running IronClaw instance in under 10 minutes. - -IronClaw ships as a single binary. You install it, run one setup command, and open the -web interface in your browser. +This guide covers both ways to run IronClaw: spin up a private instance on the Agent Hub with no installation, or install the binary on your own machine. --- -## Setting Up Your Agent +## Agent Hub (Recommended) + +The fastest way to use IronClaw — no setup, no installation. + +### 1. Sign in + +Go to [agent.near.ai](https://agent.near.ai/) and log in. Once logged in, create a new IronClaw agent. A private instance is provisioned for you. + + +You will need to provide an SSH key to connect to your private instance. If you don't have one: + +```bash +ssh-keygen -t rsa -b 4096 -C "you@example.com" +cat ~/.ssh/id_rsa.pub +``` + + + + +Add your SSH key to your device's SSH agent before connecting: + +```bash +ssh-add ~/.ssh/id_rsa +``` + + + +### 2. Talk to your agent + +Your agent is already running. You have two ways to interact: - +**Web interface (recommended):** Your [Agent Dashboard](https://agent.near.ai/) shows a web gateway link — open it in your browser for the full IronClaw WebChat experience. - +``` +https://.agents.near.ai +``` - - - Best for personal use on your own machine. Everything runs locally and no separate - database server is required. For hosted or multi-user setups, see - [Storage](/capabilities/database). +**Terminal:** Connect via SSH using the details shown in your dashboard, then start a chat session: - ```bash - curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh - ``` +```bash +ssh -p @ +ironclaw chat +``` - On Windows, use the PowerShell installer: +For one-shot commands: - ```powershell - irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex - ``` - +```bash +ironclaw run -m "Summarize my last three emails" +``` - - Go to https://agent.near.ai/ and login with your preferred method, then create an IronClaw agent in a private instance. +### 3. Manage your agent - Once your private instance is ready, you can connect to your agent's private instance through `SSH` using the address provided in the [Agent Dashboard](https://agent.near.ai/): +Use the [Agent Dashboard](https://agent.near.ai/) to start, stop, or restart your instance. Updates are handled automatically by the platform. - ```bash - ssh -p liquid-horse@agent2.near.ai - ``` +--- - +## Installing locally - To use IronClaw, you will need to provide an SSH key. If you don't have one, you can generate it using the following command in your terminal: +For personal use on your own machine with full control. - ```bash - ssh-keygen -t rsa -b 4096 -C "you@example.com" - cat ~/.ssh/id_rsa.pub - ``` +### 1. Install IronClaw - +Install the single binary: - - Remember to add your SSH key to your device's SSH agent before connecting: +```bash +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh +``` - ```bash - ssh-add ~/.ssh/id_rsa - ``` +On Windows, use the PowerShell installer: - - - +```powershell +irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex +``` Verify the install: @@ -71,13 +88,9 @@ Verify the install: ironclaw --version ``` - - - +### 2. Run setup -Run the setup command once. It creates your IronClaw home directory, writes a starter -configuration, provisions a web login token, and asks which inference provider and model -you want to use. +Create your IronClaw home directory, provision a login token, and choose your inference provider: ```bash ironclaw onboard @@ -97,7 +110,7 @@ the full list of supported providers. -Everything lives under `~/.ironclaw/reborn`: +Everything lives under `~/.ironclaw`: | File | Purpose | | --- | --- | @@ -126,9 +139,7 @@ Use `--dry-run` to see exactly what would be written without touching the filesy - - - +### 3. Start the agent Start the web interface: @@ -157,16 +168,14 @@ Print your configuration paths and read the token back: ```bash ironclaw config path -cat ~/.ironclaw/reborn/webui-token +cat ~/.ironclaw/webui-token ``` Then visit `http://127.0.0.1:3000/login?token=`. - - - +### 4. Chat with your agent Type a message in the chat and the agent will respond. From here you can also reach Projects, Jobs, Routines, and Settings from the sidebar. @@ -178,14 +187,10 @@ ironclaw repl ironclaw run -m "Summarize my last three emails" ``` - - - +### 5. Keep it running To have IronClaw start automatically in the background, install it as a system service -(launchd on macOS, systemd on Linux). Skip this step on a NEAR AI hosted instance — the -agent already runs for you, and `ironclaw service` does not work there. Use the -[Agent Dashboard](https://agent.near.ai/) to start, stop, or restart it. +(launchd on macOS, systemd on Linux): Stop the foreground `ironclaw serve` first. The service runs `serve` too, so starting it @@ -199,9 +204,7 @@ ironclaw service start ironclaw service status ``` - - - +### 6. Update IronClaw Update to the latest release: @@ -209,10 +212,6 @@ Update to the latest release: ironclaw-update ``` - - - - --- ## Next Steps diff --git a/docs/zh/capabilities/skills.mdx b/docs/zh/capabilities/skills.mdx index 649dabf85cb..5dc26d0ff6c 100644 --- a/docs/zh/capabilities/skills.mdx +++ b/docs/zh/capabilities/skills.mdx @@ -6,7 +6,7 @@ description: 基于上下文自动激活的提示扩展 Skill 是包含领域指令的 Markdown 文件。激活后，其内容会注入到 LLM 上下文中，让代理在特定场景下具备稳定、可复用的专业能力。 -IronClaw 支持从 ClawHub 社区注册表搜索和安装技能。 +IronClaw 支持从 IronHub 社区注册表搜索和安装技能。详见 [IronHub](/hub/overview) 完整目录。 --- @@ -51,7 +51,7 @@ IronClaw 支持从 ClawHub 社区注册表搜索和安装技能。 | 级别 | 来源 | 工具权限 | |------|------|----------| | Trusted | `~/.ironclaw/skills/` 或工作区 `skills/` | 与代理一致的完整权限 | -| Installed | 通过 `skill_install` 从 ClawHub 安装 | 只读工具（无 shell、无文件写入、无 HTTP） | +| Installed | 通过 `skill_install` 从 IronHub 安装 | 只读工具（无 shell、无文件写入、无 HTTP） | 不要把未经审查的 Skill 放到受信任目录。受信任 Skill 与你拥有相同级别的执行能力。 @@ -65,7 +65,7 @@ IronClaw 支持从 ClawHub 社区注册表搜索和安装技能。 |------|----------|------| | `~/.ironclaw/skills/` | Trusted | 全局技能，所有会话可用 | | `/skills/` | Trusted | 工作区技能，仅当前仓库生效 | -| `~/.ironclaw/installed_skills/` | Installed | 从 ClawHub 安装的技能 | +| `~/.ironclaw/installed_skills/` | Installed | 从 IronHub 安装的技能 | --- diff --git a/docs/zh/index.mdx b/docs/zh/index.mdx index 540abc3eaad..7091cdf082f 100644 --- a/docs/zh/index.mdx +++ b/docs/zh/index.mdx @@ -28,7 +28,7 @@ IronClaw 是一个安全、开源的 AI 智能体框架，基于 Rust 构建， - 通过 ClawHub 注册表中的 SKILL.md 提示扩展增强能力。 + 通过 IronHub 注册表中的 SKILL.md 提示扩展增强能力。