ironclaw onboard is the one-time setup command. It creates your IronClaw home
directory, writes a starter configuration, provisions the token used to sign in to the
web interface, and walks you through choosing an inference provider.
Run it once after installing. Running it again is safe — it preserves your existing
config.toml and providers.json unless you pass --force.
If you haven’t installed IronClaw yet, follow the Quickstart first.
Running Onboarding
1
Home Directory
Onboarding resolves your IronClaw home —
~/.ironclaw/reborn by default — and creates it
if it doesn’t exist. Override the location with the IRONCLAW_REBORN_HOME environment
variable.2
Configuration Files
Two files are written into that directory:
config.toml— the selection layer: boot profile, identity, model slots, runner timingproviders.json— the catalog of inference providers this install knows about
3
Master Key
Your master encryption key is provisioned in the OS keychain, where it protects every
credential IronClaw stores. It is never written to
config.toml.On a headless host without a keychain, supply the key through the
IRONCLAW_REBORN_SECRET_MASTER_KEY environment variable instead.4
Inference Provider
In an interactive terminal, onboarding asks which provider and model to use and stores
your API key. Non-interactive sessions skip this step — see below.
5
Web Login Token
A bearer token is written to
webui-token and used by ironclaw serve whenever
IRONCLAW_REBORN_WEBUI_TOKEN is unset. Onboarding prints a ready-to-use login link:6
System Service
In an interactive session, onboarding offers to install and start IronClaw as an
OS-native service (launchd on macOS, systemd on Linux) so it runs in the background. The
installed unit runs
ironclaw serve.Skip it with --no-service, or manage it later with ironclaw service install,
start, stop, restart, status, and uninstall.Decline this on a NEAR AI hosted instance, or pass
--no-service. The agent already
runs there, and ironclaw service has no user service manager to talk to, so every
service subcommand fails. Start, stop, and restart a hosted agent from the
Agent Dashboard.Options
--import-history is not wired up yet. The flag records the intent in the onboarding
summary so the missing step is explicit, but no history is imported.Non-interactive Setup
In CI, a container, or any piped invocation, onboarding detects the non-interactive session and skips both the provider prompts and the service install:Verifying Setup
Check what onboarding produced and confirm the runtime is healthy:doctor reports your home directory, active profile, whether configuration files were
found, and whether each driver initialized.
What Onboarding Doesn’t Set Up
Onboarding covers the runtime: home directory, configuration, master key, inference provider, web token, and optionally the OS service. It does not connect messaging channels. Slack and Telegram are connected afterwards, in the web interface: Extensions → Channels tab → scroll to the bottom of the Built-in section → Configure Two things trip people up here:- Extensions opens on the Registry tab, which is not where channels are connected. Using Configure from Registry on Telegram opens the pairing panel, which can only report “An administrator must configure the Telegram bot first.” That is not a permissions problem — you’re on the wrong tab.
- Asking the agent to connect a channel covers only the personal half. The operator step — registering the app or bot credentials for the instance — stays in the web interface. Once that’s done, asking the agent (“connect Slack”) works: it installs and activates the extension, an in-chat connection panel opens if your account still needs OAuth, and if your account is already connected the agent says so and continues.
Configuration
Every configuration key and how precedence works.
Inference Providers
Choose and configure your model provider.