Skip to main content

​
Overview

The ironclaw run command starts the IronClaw AI agent in default mode. This is the primary command for running the agent with all configured channels and features enabled.
If you run ironclaw without any subcommand, it will default to ironclaw run.

​
Usage

​
Global Options

These options are available for all IronClaw commands:
​
flag
Run in interactive CLI mode only, disabling all other channels (HTTP, WASM channels, etc.)
​
flag
Skip database connection. Useful for testing or running without a configured database backend.
​
string
Single message mode - send one message to the agent and exit immediately after receiving the response.
​
path
Path to a custom configuration file. By default, IronClaw uses environment variables and ~/.ironclaw/.env.
​
flag
Skip the first-run onboarding check. Use this if you’ve already completed onboarding or want to bypass it.

​
Examples

​
Start the agent normally

Or simply:

​
Run in CLI-only mode

Disable all channels except the command-line interface:

​
Send a single message

Send one message and exit:

​
Run without database

Run the agent without connecting to the database:

​
What Happens When You Run

When you execute ironclaw run, the agent:
  1. Loads configuration from environment variables and config files
  2. Connects to the database (unless --no-db is specified)
  3. Initializes the NEAR AI session for LLM access
  4. Starts configured channels (CLI, HTTP, WASM channels)
  5. Begins the heartbeat loop (if enabled in settings)
  6. Listens for messages and executes agent loops

​
Terminal Output

Typical output when starting the agent:

​
First Run

If this is your first time running IronClaw, you’ll be prompted to complete onboarding:
To skip this check, use the --no-onboard flag.

ironclaw onboard

Complete first-time setup

ironclaw status

Check system health

ironclaw config

Manage configuration settings

ironclaw doctor

Run diagnostics

​
Environment Variables

Key environment variables that affect ironclaw run:
  • DATABASE_URL - PostgreSQL connection string
  • DATABASE_BACKEND - Database backend (postgres, libsql, turso)
  • NEARAI_API_KEY - NEAR AI API key for LLM access
  • SECRETS_MASTER_KEY - Master encryption key for secrets
  • HEARTBEAT_ENABLED - Enable/disable heartbeat loop (true/false)
  • HTTP_PORT - Port for HTTP channel (default: 3000)
See Configuration for a complete list of environment variables.