ironclaw onboard

Interactive setup wizard for first-time IronClaw configuration

ironclaw onboard

Run the interactive onboarding wizard to configure IronClaw for first use. This command guides you through initial setup including authentication, channel configuration, and system validation.

Syntax

ironclaw onboard [FLAGS]

Flags

--skip-auth

Skip authentication step and use existing session.

ironclaw onboard --skip-auth

Use this when you already have a valid NEAR AI session or API key configured and only want to reconfigure other settings.

--channels-only

Reconfigure channels only, skip other setup steps.

ironclaw onboard --channels-only

Useful for adding or reconfiguring communication channels (Telegram, Slack, etc.) without going through the full onboarding flow.

Description

The onboard command is typically the first command you run after installing IronClaw. It walks you through:

1. Authentication - Setting up your NEAR AI session or API key
2. Database Configuration - Choosing and configuring your database backend
3. Secrets Encryption - Generating a master key for encrypting sensitive data
4. Channel Setup - Configuring communication channels (Telegram, Slack, Discord, etc.)
5. Validation - Checking that all dependencies are properly configured

Examples

First-Time Setup

ironclaw onboard

Run the full onboarding wizard for initial setup.

Reconfigure Channels

ironclaw onboard --channels-only

Add or update Telegram, Slack, or other communication channels without re-authenticating.

Skip Authentication

ironclaw onboard --skip-auth

Use existing authentication and configure other settings.

What Happens During Onboarding

1. Authentication

You’ll be prompted to authenticate with NEAR AI. You can:

• Use an existing NEAR AI session file
• Provide a NEAR AI API key
• Skip if --skip-auth is set

The session information is stored in:

• ~/.nearai/session (default session file)
• .env file (if using NEARAI_API_KEY)

2. Database Backend

Choose your database backend:

• PostgreSQL - Production-ready, recommended for multi-user deployments
• libSQL - Local SQLite-compatible database, great for single-user setups
• Turso - Managed libSQL with replication

Configuration is saved to .env file:

# PostgreSQL
DATABASE_BACKEND=postgres
DATABASE_URL=postgresql://user:password@localhost/ironclaw

# libSQL
DATABASE_BACKEND=libsql
LIBSQL_PATH=/Users/you/.ironclaw/ironclaw.db

3. Secrets Master Key

A master key is generated for encrypting secrets (API keys, tokens, etc.). This is saved to:

SECRETS_MASTER_KEY=<generated-key>

Important: Keep this key safe! It’s required to decrypt your stored secrets.

4. Channel Configuration

Configure communication channels:

• Telegram - Bot token and optional webhook settings
• Slack - App token and bot token
• Discord - Bot token
• CLI - Enabled by default

Each channel has its own configuration section in .env.

5. Validation

The wizard validates:

• Database connectivity
• Session file or API key validity
• Directory permissions
• Required environment variables

Files Created

Onboarding creates/modifies:

• .env - Environment variables and configuration
• ~/.nearai/session - NEAR AI session file (if not using API key)
• ~/.ironclaw/ - Base directory for data storage
• ~/.ironclaw/ironclaw.db - libSQL database (if using libSQL backend)

Troubleshooting

”Session file not found”

You need to authenticate with NEAR AI:

# Set API key
export NEARAI_API_KEY=your-api-key

# Or create session file
mkdir -p ~/.nearai
echo "your-session-token" > ~/.nearai/session

“Database connection failed”

Check your database is running:

# PostgreSQL
psql $DATABASE_URL -c "SELECT 1"

# libSQL creates the file automatically, check permissions
ls -la ~/.ironclaw/

“Permission denied”

Ensure the IronClaw base directory is writable:

mkdir -p ~/.ironclaw
chmod 700 ~/.ironclaw

Re-running Onboarding

You can safely re-run onboarding at any time. It will:

• Preserve existing settings where possible
• Prompt before overwriting configuration
• Allow you to update specific settings

Use the flags to skip sections you don’t want to reconfigure:

# Only reconfigure channels
ironclaw onboard --channels-only

# Keep existing auth, configure everything else
ironclaw onboard --skip-auth

Next Steps

After onboarding:

1. Run diagnostics: ironclaw doctor
2. Install tools: ironclaw tool install <path>
3. Add MCP servers: ironclaw mcp add <name> <url>
4. Start the agent: ironclaw or ironclaw run

Related Commands

• doctor - Verify your configuration
• config - View and modify settings
• service install - Install as system service