Skill Allowlisting — Authorise Skills & Grant Permissions

How the Allowlist Works

Every skill in IronClaw has two independent states:

• Installed — the skill package is on disk, the agent knows it exists
• Authorised — you have explicitly granted this skill permission to execute

An installed-but-not-authorised skill is invisible to the agent at runtime. If the agent tries to call it (because it was mentioned in a SOUL.md or a user prompt), IronClaw intercepts the call, logs an ALLOWLIST_DENY event to the audit log, and returns an error to the agent explaining that the skill is not authorised.

This matters because it closes the gap that supply-chain attacks exploit in OpenClaw: even if a malicious skill is installed via a dependency or a compromised update, it cannot run without an explicit allowlist entry created by you on the command line.

The Allowlist File

The allowlist lives at ~/.ironclaw/allowlist.json. It's a JSON file you can edit directly or manage via the CLI. Always use the CLI for changes — it validates the format and reloads the gateway automatically:

{
  "version": "1",
  "skills": {
    "daily-brief": {
      "authorised": true,
      "grants": {
        "network": [],
        "filesystem": ["~/.ironclaw/workspace"],
        "shell": false,
        "env": []
      },
      "authorisedAt": "2026-04-06T09:12:00Z",
      "authorisedBy": "cli"
    },
    "github": {
      "authorised": true,
      "grants": {
        "network": ["api.github.com:443", "github.com:443"],
        "filesystem": ["~/.ironclaw/workspace"],
        "shell": false,
        "env": ["GITHUB_TOKEN"]
      },
      "authorisedAt": "2026-04-06T10:05:00Z",
      "authorisedBy": "cli"
    }
  }
}

Each skill entry has four grant categories:

CLI Reference

Add a skill to the allowlist (no network, workspace-only)

ironclaw allowlist add daily-brief

# Output:
# ✓ daily-brief authorised
# grants: network=none, filesystem=workspace, shell=false, env=none
# Gateway reloaded — skill active immediately

Add a skill with network access

ironclaw allowlist add github \
  --network "api.github.com:443,github.com:443,raw.githubusercontent.com:443"

# Shorthand: --network accepts comma-separated host:port pairs

Add a skill with shell access (use sparingly)

# Only do this for skills you have read and understand
ironclaw allowlist add system-info --shell

# IronClaw prompts for confirmation when --shell is used:
# WARNING: Granting shell access lets this skill run arbitrary commands.
# Have you read the skill source code? [y/N]

Grant a specific environment variable

ironclaw allowlist grant github --env GITHUB_TOKEN

Grant additional network access to an existing skill

ironclaw allowlist grant himalaya --network "imap.gmail.com:993,smtp.gmail.com:587"

List all allowlisted skills

ironclaw allowlist list

# Output:
# SKILL          STATUS       NETWORK                    SHELL  ENV
# daily-brief    authorised   none                       no     none
# github         authorised   api.github.com:443 (+2)   no     GITHUB_TOKEN
# himalaya       authorised   imap.gmail.com:993 (+1)   no     none

Show full grants for a specific skill

ironclaw allowlist show github

# Output:
# Skill: github
# Authorised: 2026-04-06T10:05:00Z
# Network:
#   api.github.com:443
#   github.com:443
#   raw.githubusercontent.com:443
# Filesystem: ~/.ironclaw/workspace (rw)
# Shell: no
# Env: GITHUB_TOKEN

Remove a skill from the allowlist

ironclaw allowlist remove github

# The skill remains installed but becomes inert immediately.
# All its grants are revoked.

Revoke a specific grant without removing the skill

# Remove shell access from a skill
ironclaw allowlist revoke system-info --shell

# Remove a specific network grant
ironclaw allowlist revoke himalaya --network "smtp.gmail.com:587"

Allowlisting Official Skills — Quick Reference

The 53 official OpenClaw skills all work in IronClaw. Here are the correct grants for the most commonly used ones:

Example — allowlist the weather skill in one command:

ironclaw skill install weather
ironclaw allowlist add weather --network "api.open-meteo.com:443,geocoding-api.open-meteo.com:443"

Writing Custom Skills for IronClaw

Custom skills work the same way as OpenClaw — you (or your agent) write a SKILL.md file. The only difference: you need to declare what permissions the skill needs in the SKILL.md so you know what to grant when allowlisting.

Ask your agent to write a skill that declares its requirements explicitly:

"Write me a skill that checks my server uptime at https://status.example.com/api/status. Format it as an IronClaw-compatible SKILL.md. In the permissions section, list every network host and port it needs — I'll use that to write the allowlist entry."

A good IronClaw-compatible SKILL.md includes a ## Permissions section:

# SKILL: server-status

## Description
Checks server uptime from a status API endpoint.

## Permissions
- network: status.example.com:443
- filesystem: none beyond workspace
- shell: no
- env: none

## Implementation
...skill code...

Then allowlist it with exactly what the skill declared:

ironclaw allowlist add server-status --network "status.example.com:443"

If the skill tries to access anything beyond what you granted, IronClaw blocks it and logs the attempt. This makes it easy to audit whether a skill is behaving as expected.

What Happens When a Skill Exceeds Its Grants

If a skill attempts a network connection, file access, or shell command that isn't in its grants:

1. The call is blocked immediately — the skill does not complete the action
2. An ALLOWLIST_VIOLATION event is written to the audit log with: skill name, attempted action, blocked resource, timestamp
3. The agent receives an error and reports it to you
4. The skill remains authorised — a single violation doesn't revoke it

# View recent violations
ironclaw audit tail --filter ALLOWLIST_VIOLATION

# Example output:
# [2026-04-06T11:23:01Z] ALLOWLIST_VIOLATION skill=himalaya action=network host=phishing-site.com:443
# [2026-04-06T11:23:02Z] ALLOWLIST_VIOLATION skill=himalaya action=network host=attacker.io:80

Multiple violations from the same skill in a short window indicate either a misconfigured grant (you forgot to add a host) or a compromised skill. IronClaw can auto-suspend a skill after N violations in a time window — configure this in the security config.

Exporting and Importing the Allowlist

The allowlist is a plain JSON file — back it up, version-control it, and restore it on a new machine:

# Export
cp ~/.ironclaw/allowlist.json ~/allowlist-backup-$(date +%F).json

# Or use the CLI export (strips timestamps, good for sharing configs)
ironclaw allowlist export > ~/my-allowlist.json

# Import on a new machine (after installing IronClaw and skills)
ironclaw allowlist import ~/my-allowlist.json
# Prompts you to confirm each skill and its grants before applying