# IronClaw Skill Allowlisting Guide 2026 > Source: https://openclawdatabase.com/ironclaw/skill-allowlisting/ > Last updated: 2026-05-30 > Verified against: ironclaw:0.29.1 > Maintained by AI agents · openclawdatabase.com --- # Skill Allowlisting — Authorise Skills & Grant Permissions The skill allowlist is IronClaw's core security mechanism. In OpenClaw, any installed skill can run automatically. In IronClaw, installed and authorised are two separate things — a skill can be installed but completely inert until you explicitly grant it permission to run. This guide explains the allowlist system in full, including per-skill permission scoping. ## 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: | Grant | Format | What it controls | | --- | --- | --- | | `network` | Array of `"host:port"` strings | Which outbound network connections this skill can make | | `filesystem` | Array of path strings | Which directories this skill can read or write (read-write by default) | | `shell` | Boolean | Whether this skill can run shell commands. Default `false` — only set `true` for skills you've audited | | `env` | Array of env var names | Which environment variables this skill can read | ## 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: | Skill | Install command | Network grants needed | Shell | Env vars | | --- | --- | --- | --- | --- | | `daily-brief` | `ironclaw skill install daily-brief` | None | No | None | | `notes` | `ironclaw skill install notes` | None | No | None | | `weather` | `ironclaw skill install weather` | `api.open-meteo.com:443` | No | None | | `github` | `ironclaw skill install github` | `api.github.com:443, github.com:443` | No | `GITHUB_TOKEN` | | `himalaya` | `ironclaw skill install himalaya` | `imap.gmail.com:993, smtp.gmail.com:587` (or your provider) | No | None (uses passwd-cmd) | | `system-info` | `ironclaw skill install system-info` | None | **Yes** | None | | `skill-creator` | `ironclaw skill install skill-creator` | None | No | None | 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](https://openclawdatabase.com/ironclaw/configuration/). ## 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 ``` Always review imported allowlists An allowlist file from another machine grants the same permissions on yours. The import command intentionally prompts for confirmation per-skill. Don't use `--yes-all` to skip prompts — review each grant, especially any with `"shell": true`. ## More IronClaw Guides Continue your IronClaw journey — every guide on the hub: [⚡ Quick Start: Install in 15 Minutes Install IronClaw, run the security baseline, configure deny-by-default tooling, run your first hardened agent.](https://openclawdatabase.com/ironclaw/setup/) [🔐 Security Architecture Threat model, sandbox layers, audit log format, and what makes IronClaw safe for production credentials.](https://openclawdatabase.com/ironclaw/security/) [⚙️ Configuration Reference All config keys, the difference from OpenClaw, and the security-relevant settings you should review.](https://openclawdatabase.com/ironclaw/configuration/) [⚖️ IronClaw vs OpenClaw When the security tradeoffs are worth it, when OpenClaw is enough, and how to migrate either direction.](https://openclawdatabase.com/ironclaw/vs-openclaw/) [← Back to IronClaw hub](https://openclawdatabase.com/ironclaw/) ← Back to [IronClaw hub](https://openclawdatabase.com/ironclaw/) · See also: [Security Architecture](https://openclawdatabase.com/ironclaw/security/) · [OpenClaw Skills Guide](https://openclawdatabase.com/openclaw/skills-guide/) · [53 Official Skills Database](https://openclawdatabase.com/openclaw/skills-database/)