IronClaw Quick Start — Install, Onboard & First Run

Option A: hosted on the Agent Hub (no install)

Sign in at agent.near.ai and create an IronClaw agent; a private instance is provisioned for you (you'll add an SSH key). Open the web gateway link from the dashboard (https://<instance-id>.agents.near.ai), or SSH in and use the terminal. Start, stop and restart it from the dashboard. ironclaw service commands don't work on hosted instances, and updates are automatic.

Option B: on your own machine

1. Install

# macOS, Linux, Windows/WSL
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh

# Windows PowerShell
irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex

ironclaw --version

There's also a Windows MSI, and a source build (cargo install --locked --path crates/app/ironclaw_cli). To pin a specific release, use the installer URL from that release's page instead of latest.

2. Onboard

ironclaw onboard

One-time setup. It:

• creates your IronClaw home (~/.ironclaw/reborn by default; override with IRONCLAW_REBORN_HOME);
• writes config.toml and providers.json;
• puts the master encryption key in the OS keychain (on a headless host, supply IRONCLAW_REBORN_SECRET_MASTER_KEY);
• asks for an inference provider and key;
• writes a web login token, and prints a link like http://127.0.0.1:3000/login?token=….

On macOS and Linux it offers to install the background service too. Re-running it is safe; --force overwrites your config. NEAR AI is the recommended provider for privacy. The catalogue also covers Anthropic, OpenAI (including a ChatGPT-subscription route), Gemini, Bedrock, Ollama, OpenRouter, Groq, DeepSeek and any OpenAI-compatible endpoint.

Scripted install: ironclaw onboard --no-service < /dev/null, then ironclaw models set-provider anthropic --model <model>, or export the provider's key. --dry-run shows what would be written.

3. Start it

ironclaw serve                 # web interface on 127.0.0.1:3000 (local only)
ironclaw serve --port 3100     # if 3000 is taken
ironclaw repl                  # or chat in the terminal
ironclaw run -m "Summarize my last three emails"

Lost the login link? ironclaw config path shows where the webui-token file is.

4. Keep it running

# stop the foreground server first (it holds the port), then:
ironclaw service install
ironclaw service start
ironclaw service status

A launchd user agent on macOS, a systemd user unit on Linux. stop, restart and uninstall are also available.

5. Check it

ironclaw doctor    # config and driver health, creates no state
ironclaw status    # runtime snapshot and the login link again

Channels, extensions and skills

Onboarding doesn't connect messaging apps. IronClaw supports Slack and Telegram, and setup has two halves in the web interface: an operator saves the bot or app credentials under Admin → Configuration, then each person connects under Extensions. Tools and skills come from extensions and the signed IronHub catalogue. See skills, tools & allowlisting.

Updating

ironclaw-update

Releases since 1.1.0 added per-user model preferences, structured automations and document editing (1.3.0). 1.4.0 added a durable notification inbox, background subagents, persistent per-user sandbox containers on the local-Docker profile and a managed egress proxy. 1.4.1 (2026-09-29) is the current stable release. Gmail and Google Calendar can be activated when the operator supplies the Google OAuth client through the web UI instead of environment variables. Before 1.4.1, authorization completed but activation failed and revoked the credential it had just issued, so every retry failed again. Administrator configuration now takes precedence over deployment (environment or config.toml) client material; deployments that bake in client credentials and never open the administrator form are unaffected. It also updates the WASM runtime (see security).

Coming from the old 0.29.x line? 1.x was a ground-up rebuild with no automatic migration of 0.29 config, databases or secrets. Point IRONCLAW_REBORN_HOME at a new directory and set it up fresh.