ironclaw tool - IronClaw

Overview

The ironclaw tool command provides subcommands for managing WebAssembly (WASM) tools. Tools are sandboxed plugins that extend the agent’s capabilities with custom functionality.

Subcommands

install

Install a WASM tool from source or a compiled .wasm file:

ironclaw tool install <PATH> [OPTIONS]

path

required

Path to tool source directory (with Cargo.toml) or a .wasm file.

string

Tool name. Defaults to the crate name from Cargo.toml or the filename.

path

Path to capabilities JSON file. Auto-detected if not specified.

path

Installation directory. Defaults to ~/.ironclaw/tools/.

boolean

default:"true"

Build in release mode (optimized).

flag

Skip compilation and use an existing .wasm file.

flag

Overwrite if the tool already exists.

Examples:

# Install from source directory
ironclaw tool install ~/my-tools/weather-tool/

# Install a pre-built .wasm file
ironclaw tool install ~/downloads/calculator.wasm

# Install with custom name
ironclaw tool install ./tool --name my-custom-tool

# Force overwrite existing installation
ironclaw tool install ./tool --force

Output:

Installing weather-tool to /home/user/.ironclaw/tools/weather-tool.wasm
  Copying capabilities from weather-tool.capabilities.json

Installed successfully:
  Name: weather-tool
  WASM: /home/user/.ironclaw/tools/weather-tool.wasm
  Size: 245760 bytes
  Hash: a3f9c8e2b1d47f5a
  Caps: /home/user/.ironclaw/tools/weather-tool.capabilities.json

list

List installed tools:

ironclaw tool list [OPTIONS]

path

Directory to list tools from. Defaults to ~/.ironclaw/tools/.

flag

Show detailed information including capabilities and permissions.

Examples:

ironclaw tool list
ironclaw tool list --verbose

Output (normal):

Installed tools in /home/user/.ironclaw/tools:

  calculator (42.3 KB, caps: ✓)
  weather-tool (240.0 KB, caps: ✓)
  notion-sync (156.8 KB, caps: ✓)

Output (verbose):

Installed tools in /home/user/.ironclaw/tools:

  weather-tool (240.0 KB)
    Path: /home/user/.ironclaw/tools/weather-tool.wasm
    Hash: a3f9c8e2
    Caps: yes
    Perms: http: api.openweathermap.org, secrets: 1

  notion-sync (156.8 KB)
    Path: /home/user/.ironclaw/tools/notion-sync.wasm
    Hash: f2a8c9d1
    Caps: yes
    Perms: http: api.notion.com, workspace: read

remove

Remove an installed tool:

ironclaw tool remove <NAME> [OPTIONS]

string

required

Name of the tool to remove.

path

Directory to remove tool from. Defaults to ~/.ironclaw/tools/.

Example:

ironclaw tool remove weather-tool

Output:

Removed /home/user/.ironclaw/tools/weather-tool.wasm
Removed /home/user/.ironclaw/tools/weather-tool.capabilities.json

Tool 'weather-tool' removed.

info

Show detailed information about a tool:

ironclaw tool info <NAME_OR_PATH> [OPTIONS]

string

required

Tool name or path to a .wasm file.

path

Directory to look for tool. Defaults to ~/.ironclaw/tools/.

Example:

ironclaw tool info weather-tool

Output:

Tool: weather-tool
Path: /home/user/.ironclaw/tools/weather-tool.wasm
Size: 245760 bytes (240.0 KB)
Hash: a3f9c8e2b1d47f5ac3e8d9a2f1c4b7e8

Capabilities (/home/user/.ironclaw/tools/weather-tool.capabilities.json):
  HTTP:
    GET,POST api.openweathermap.org /*
  Credentials:
    api_key: openweather_api_key -> header:X-API-Key
  Rate limit: 60/min, 1000/hour
  Secrets (existence check only):
    openweather_api_key

auth

Configure authentication for a tool (OAuth or token-based):

ironclaw tool auth <NAME> [OPTIONS]

string

required

Name of the tool to authenticate.

path

Directory to look for tool. Defaults to ~/.ironclaw/tools/.

string

default:"default"

User ID for storing the secret.

Example:

ironclaw tool auth notion-sync

OAuth Flow Output:

╔════════════════════════════════════════════════════════════════╗
║                     Notion Authentication                      ║
╚════════════════════════════════════════════════════════════════╝

  Starting OAuth authentication...

  Opening browser for Notion login...

  Waiting for authorization...

  Exchanging code for token...

  ✓ Notion connected!

  The tool can now access the API.

Manual Token Entry:

╔════════════════════════════════════════════════════════════════╗
║                   OpenWeather Authentication                   ║
╚════════════════════════════════════════════════════════════════╝

  Setup instructions:

    1. Go to https://openweathermap.org/api
    2. Sign up for a free account
    3. Navigate to API Keys
    4. Copy your API key

  Press Enter to open setup page (or 's' to skip): 

  Token format: sk-...

  Paste your token: ********************

  Validating token... ✓

  ✓ OpenWeather connected!

  The tool can now access the API.

setup

Configure required secrets for a tool:

ironclaw tool setup <NAME> [OPTIONS]

string

required

Name of the tool to set up.

path

Directory to look for tool. Defaults to ~/.ironclaw/tools/.

string

default:"default"

User ID for storing secrets.

Example:

ironclaw tool setup database-tool

Output:

╔════════════════════════════════════════════════════════════════╗
║                       Database Tool Setup                      ║
╚════════════════════════════════════════════════════════════════╝

  Database host: ********************
    ✓ Saved.

  Database password: ********************
    ✓ Saved.

  API key (optional, Enter to skip): 
    Skipped.

  ✓ Database Tool setup complete!

Tool Capabilities

Tools must include a .capabilities.json file that defines their permissions:

{
  "http": {
    "allowlist": [
      {
        "host": "api.openweathermap.org",
        "methods": ["GET"],
        "path_prefix": "/data/2.5"
      }
    ],
    "credentials": {
      "api_key": {
        "secret_name": "openweather_api_key",
        "location": {"header": "X-API-Key"}
      }
    },
    "rate_limit": {
      "requests_per_minute": 60,
      "requests_per_hour": 1000
    }
  },
  "secrets": {
    "allowed_names": ["openweather_api_key"]
  }
}

Tools without a capabilities file will run with no permissions (default deny).

Building WASM Tools

To build a tool from source:

Create a Rust project targeting wasm32-wasip1:
cargo new --lib my-tool cd my-tool
Add WASM target:
rustup target add wasm32-wasip1

Build the component:

cargo build --release --target wasm32-wasip1

Install with IronClaw:
ironclaw tool install .

See the Tool Development Guide for details.

ironclaw mcp

Manage MCP servers

ironclaw status

View installed tool count

​Overview

​Subcommands

​install

​list

​remove

​info

​auth

​setup

​Tool Capabilities

​Building WASM Tools

​Related Commands

ironclaw mcp

ironclaw status

Overview

Subcommands

install

list

remove

info

auth

setup

Tool Capabilities

Building WASM Tools

Related Commands