> ## 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

> 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

```bash theme={null}
ironclaw onboard [FLAGS]
```

## Flags

### `--skip-auth`

Skip authentication step and use existing session.

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
ironclaw onboard
```

Run the full onboarding wizard for initial setup.

### Reconfigure Channels

```bash theme={null}
ironclaw onboard --channels-only
```

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

### Skip Authentication

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
# 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](/cli/doctor) - Verify your configuration
* [config](/cli/config) - View and modify settings
* [service install](/cli/service) - Install as system service