Skip to main content

​
Overview

The ironclaw onboard command launches an interactive wizard that guides you through initial configuration of IronClaw. This includes authentication, database setup, and channel configuration.
Run this command when setting up IronClaw for the first time, or to reconfigure your installation.

​
Usage

​
Options

​
flag
Skip the authentication step and use your existing NEAR AI session.Use this if you’ve already authenticated and don’t want to log in again.
​
flag
Reconfigure channels only, skipping authentication and other setup steps.Useful when you want to enable/disable specific channels without redoing the full setup.

​
Examples

​
Complete onboarding

Run the full setup wizard:

​
Skip authentication

Use your existing session and configure the rest:

​
Reconfigure channels only

Change which channels are enabled without touching authentication:

​
Onboarding Steps

The onboarding wizard walks you through the following steps:

​
1. NEAR AI Authentication

Authenticate with NEAR AI to enable LLM access:
You can skip this step with --skip-auth if you’ve already authenticated.

​
2. Database Configuration

Choose and configure your database backend:

​
3. Secrets Master Key

Generate or provide a master encryption key for storing secrets:

​
4. Channel Configuration

Choose which communication channels to enable:
This step can be rerun independently with --channels-only.

​
5. Complete

​
Configuration Files Created

Onboarding creates or updates the following files:
  • ~/.ironclaw/.env - Environment variables and configuration
  • ~/.ironclaw/session.json - NEAR AI authentication session
  • ~/.ironclaw/ironclaw.db - Local database (if using libSQL)
The .env file contains sensitive credentials. Keep it secure and never commit it to version control.

​
Troubleshooting

If your browser doesn’t open automatically:
  1. Copy the authentication URL shown in the terminal
  2. Open it manually in your browser
  3. Complete the login flow
  4. Return to the terminal to continue
If PostgreSQL connection fails:
  1. Verify your DATABASE_URL is correct
  2. Check that PostgreSQL is running
  3. Ensure the database exists
  4. Verify network connectivity and firewall rules
Alternatively, choose libSQL for a local embedded database that requires no setup.
If the master key fails to save to the keychain:
  1. The key will be saved to .env instead
  2. On macOS, you may need to grant keychain access
  3. On Linux, ensure libsecret is installed
You can also set SECRETS_MASTER_KEY manually in .env.

​
Reconfiguration

You can rerun onboarding at any time to reconfigure your installation:
Existing configuration will be preserved unless you explicitly change it during the wizard.

ironclaw run

Start the agent after onboarding

ironclaw config

View and modify settings

ironclaw status

Verify your configuration

ironclaw doctor

Diagnose configuration issues