Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt

Use this file to discover all available pages before exploring further.

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us