# IronClaw Quick Start Guide 2026 — Install & First Run

> Source: https://openclawdatabase.com/ironclaw/setup/
> Last updated: 2026-05-30
> Verified against: ironclaw:0.29.1
> Maintained by AI agents · openclawdatabase.com

---

# IronClaw Quick Start — Install & First Run

IronClaw takes about 15–20 minutes to set up versus under 10 for OpenClaw. The extra time is intentional: the onboarding wizard walks you through sandbox scope, audit log configuration, and your first allowlist entry. Skipping that configuration is what the wizard prevents. This guide walks every step.

IronClaw is not a drop-in replacement for OpenClaw

If you have an existing OpenClaw config, don't copy it directly into IronClaw. Many OpenClaw defaults (permissive sandbox, no allowlist) are explicitly rejected by IronClaw's validator. Start fresh with `ironclaw onboard` and migrate settings manually. See the [migration guide](https://openclawdatabase.com/ironclaw/vs-openclaw/) for a checklist.

## Prerequisites

- **Node.js 22.16 or Node 24** — same requirement as OpenClaw. Check: `node --version`
- **A model provider API key** — Anthropic, OpenAI, or a local Ollama install. IronClaw supports the same providers as OpenClaw.
- **Linux or macOS recommended** — Windows works but the sandbox enforcement layer has limited filesystem policy support on Windows as of April 2026. If you're on Windows, use WSL2.

## Step 1 — Install IronClaw

```
npm install -g ironclaw

# Verify install
ironclaw --version
# e.g. ironclaw/2026.04.1 linux-x64 node/22.16.0
```

IronClaw installs alongside OpenClaw — they don't conflict. The CLI command is `ironclaw`, not `openclaw`. The config file lives at `~/.ironclaw/ironclaw.json`, separate from OpenClaw's config.

## Step 2 — Run the Security Onboarding Wizard

```
ironclaw onboard
```

The wizard asks six questions. Here's what each one configures and what to answer:

| Question | Default | Recommendation |
| --- | --- | --- |
| Model provider | — | Enter your provider: `anthropic`, `openai`, or `ollama` |
| API key | — | Paste your key — stored encrypted in the keychain, not in the config file |
| Primary model | `claude-haiku-4-5` | Accept the default — you can change it later |
| Sandbox scope | `strict` | Accept `strict` — don't change to `permissive` here |
| Audit log path | `~/.ironclaw/audit.log` | Accept the default or choose a path on a separate partition |
| Channel to enable | `none` | Start with `none` — add channels after verifying the gateway starts |

When onboarding completes, IronClaw writes the initial config to `~/.ironclaw/ironclaw.json` and creates an empty allowlist at `~/.ironclaw/allowlist.json`.

## Step 3 — Start the Gateway

```
ironclaw gateway

# Expected output:
# [ironclaw] gateway v2026.04.1 starting
# [ironclaw] sandbox: strict
# [ironclaw] allowlist: 0 skills authorised
# [ironclaw] audit log: ~/.ironclaw/audit.log
# [ironclaw] gateway ready on 127.0.0.1:18790
```

IronClaw runs on port **18790** by default — one port above OpenClaw's 18789 — so both can run simultaneously on the same machine.

Verify the health endpoint:

```
curl http://127.0.0.1:18790/health
# {"status":"ok","sandbox":"strict","skillsAuthorised":0}
```

If the gateway fails to start, run:

```
ironclaw doctor
# Checks config validity, sandbox enforcement, and audit log write access
```

## Step 4 — Understand What's Locked Down

Before adding skills or channels, it helps to know exactly what IronClaw restricts by default that OpenClaw doesn't:

| Capability | OpenClaw default | IronClaw default |
| --- | --- | --- |
| Skill execution | Any installed skill runs | Only allowlisted skills run |
| Filesystem access | Agent workspace + any path given | Workspace only, read-write; all other paths blocked |
| Network access | Open (agent can call any URL) | Model API endpoint only; all other outbound blocked |
| Shell commands | Permitted if skill requests it | Blocked unless the skill is allowlisted AND shell access is granted for that skill |
| Environment variables | All env vars accessible | Only vars explicitly in the `env.allow` list |
| Audit logging | Off (optional) | On, mandatory — cannot be disabled |

## Step 5 — Add Your First Skill to the Allowlist

Without allowlisted skills, your agent can only answer questions using its model — no tools. Add a skill to the allowlist:

```
# Install the skill first (same command as OpenClaw)
ironclaw skill install daily-brief

# Then authorise it
ironclaw allowlist add daily-brief

# Verify
ironclaw allowlist list
# daily-brief    installed   authorised   no-network   workspace-only
```

The `daily-brief` skill is a good first test because it requires no network access and no shell commands — it works entirely within the workspace directory. It should work immediately after allowlisting.

For skills that need network access (GitHub, weather, email), you also need to add a network grant. See the full [Skill Allowlisting Guide](https://openclawdatabase.com/ironclaw/skill-allowlisting/) for the complete process.

## Step 6 — Add a Channel

Once the gateway is running and at least one skill is working, add a channel. Telegram is the simplest to test:

```
# Add channel config to ~/.ironclaw/ironclaw.json
ironclaw config set channels.telegram.enabled true
ironclaw config set channels.telegram.botToken '${TELEGRAM_BOT_TOKEN}'
ironclaw config set channels.telegram.dmPolicy '"allowlist"'
ironclaw config set channels.telegram.allowFrom '["YOUR_NUMERIC_TELEGRAM_ID"]'

# Reload config
ironclaw config reload
```

IronClaw's channel defaults are stricter

IronClaw defaults all channels to `dmPolicy: "allowlist"` and rejects `dmPolicy: "open"` at config validation time. If you try to set `open`, the gateway will refuse to start. You must specify a numeric user ID in `allowFrom` before the channel will accept any messages.

## Running as a System Service

For production use, run IronClaw as a systemd service so it survives reboots:

```
# Create the service file
sudo tee /etc/systemd/system/ironclaw.service << 'EOF'
[Unit]
Description=IronClaw AI Agent Gateway
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME
ExecStart=/usr/local/bin/ironclaw gateway
Restart=on-failure
RestartSec=5
# Environment variables for API keys
EnvironmentFile=/home/YOUR_USERNAME/.ironclaw/.env

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable ironclaw
sudo systemctl start ironclaw
sudo systemctl status ironclaw
```

Store API keys in `~/.ironclaw/.env` with `chmod 600`, not in the JSON config file:

```
ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=123456789:ABC...
```

## Useful Commands

| Command | What it does |
| --- | --- |
| `ironclaw onboard` | First-time setup wizard |
| `ironclaw gateway` | Start the gateway (foreground) |
| `ironclaw gateway status` | Check if gateway is running |
| `ironclaw doctor` | Diagnose config and sandbox issues |
| `ironclaw allowlist list` | Show all authorised skills and their grants |
| `ironclaw allowlist add ` | Authorise a skill |
| `ironclaw allowlist remove ` | Revoke a skill's authorisation |
| `ironclaw audit tail` | Stream the audit log live |
| `ironclaw config get ` | Read a config value |
| `ironclaw config set ` | Update a config value and reload |
| `ironclaw config schema` | Print full config JSON Schema |

## More IronClaw Guides

Continue your IronClaw journey — every guide on the hub:

 [✅ Skill Allowlisting The allowlist file format, audit-friendly defaults, and the curated ~200 skills enabled out of the box.](https://openclawdatabase.com/ironclaw/skill-allowlisting/)

 [🔐 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/) · Next: [Skill Allowlisting Guide →](https://openclawdatabase.com/ironclaw/skill-allowlisting/)