How it works
Ironheights is a command-line tool that runs on your machine. It does three things: it scans skill files for risky patterns, it records a baseline of your installed skills and agent files, and it tells you when that baseline no longer matches.
1. Scan: read skills as data
A skill is a folder with a SKILL.md and sometimes scripts. Ironheights walks the folder within the limits you set (file size, file count, depth), reads each file as text, and matches it against fixed rules. It never executes a file, and it does not extract archives; a bundled archive is a finding on its own.
2. Score: findings become a verdict
Each finding has a rule id, severity, confidence, file and line, the evidence, a message, and a remediation. Severities add up to a score: critical 100, high 40, medium 15, low 5, info 0.
- block: any critical finding, or a score of 80 or more.
- review: any high or medium finding, or a score of 15 or more.
- no-findings: nothing matched. This is not proof of safety.
- incomplete: a file was skipped (for example one over 1 MiB) or a
.gitornode_modulesdirectory was not entered, and nothing that was scanned reached review or block. The exit code is 3, and each skipped file and directory is named in the report. Review and block still win;--allow-skippedaccepts what was skipped.
Every scan also prints an A to F grade, a 0 to 100 score built from the same points (A is 90 or more, F is below 60). It is a summary, not a safety rating, and a scan that skipped anything is graded incomplete.
Thresholds are configurable in ironheights.config.json, and individual rules can be disabled or re-rated with ruleOverrides.
3. Baseline and verify: notice what changed
ironheights baseline create writes a file with a sha256, size, and mode for each watched path, plus a tree hash. Watched paths default to your skill directories and agent files such as AGENTS.md, SOUL.md, MEMORY.md, openclaw.json, credentials/, and .env under the OpenClaw state directory.
ironheights verify reports files that were added, modified, removed, or had their mode changed since the baseline. These are the integrity rules. With --key, the baseline is also signed and checked, so an edited baseline shows up as tampered.
4. Quarantine: move, do not delete
ironheights quarantine <skill> moves a skill into a private quarantine directory so the agent stops loading it. ironheights quarantine restore <id> moves it back. Ironheights does not delete a skill on its own.
New in 0.3.0: before, during and after
Before you install: ironheights safe-install <owner>/<slug> downloads a ClawHub skill, scans it, and installs it only when the verdict is no-findings. The CLI can also use a signed advisory feed to match known-bad skills, though that feed is not published yet.
While the agent runs: the optional guard plugin watches a short list of tool calls and logs them. It is not a sandbox.
After something changes: a signed baseline and verify catch edits to your skills and agent files, including edits to the baseline itself. See every command and limit on the features page.
The advisory OpenClaw skill
An optional skill tells your agent to run ironheights scan <path> --json, summarize the result, and stop on a block verdict until you confirm. It asks for no network access and no secrets. Because it runs inside the agent, a hostile skill can try to bypass it. The CLI you run yourself is the trusted path.
What is not built yet
A sandbox or egress proxy, a credential broker, full injection screening of inbound content, and a team console are on the roadmap. They are not part of version 0.3.0. The guard plugin and the text scan are early, partial steps in that direction, not replacements. See Limitations and Pricing.