ironclaw doctor

Run diagnostics and validate IronClaw configuration

ironclaw doctor

Run comprehensive health diagnostics to validate your IronClaw configuration and check external dependencies. Use this command to troubleshoot issues before they affect normal operation.

Syntax

ironclaw doctor

Description

The doctor command performs a series of checks to verify:

1. Authentication - NEAR AI session or API key
2. Database - Database backend connectivity
3. Workspace - Directory existence and permissions
4. External binaries - Docker, cloudflared, ngrok, tailscale

Each check reports:

• [pass] - Check succeeded
• [FAIL] - Check failed (requires attention)
• [skip] - Binary not found (normal if not used)

Examples

# Run all diagnostics
ironclaw doctor

Output

Successful Run

IronClaw Doctor
===============

  [pass] NEAR AI session: session found (/Users/you/.nearai/session)
  [pass] Database backend: PostgreSQL connected
  [pass] Workspace directory: /Users/you/.ironclaw
  [pass] Docker: Docker version 24.0.6, build ed223bc
  [skip] cloudflared: cloudflared not found in PATH
  [skip] ngrok: ngrok not found in PATH
  [skip] tailscale: tailscale not found in PATH

  4 passed, 0 failed

With Failures

IronClaw Doctor
===============

  [FAIL] NEAR AI session: session file not found at /Users/you/.nearai/session. Run `ironclaw onboard`
  [pass] Database backend: libSQL database exists (/Users/you/.ironclaw/ironclaw.db)
  [pass] Workspace directory: /Users/you/.ironclaw
  [pass] Docker: Docker version 24.0.6, build ed223bc
  [skip] cloudflared: cloudflared not found in PATH
  [skip] ngrok: ngrok not found in PATH
  [skip] tailscale: tailscale not found in PATH

  3 passed, 1 failed

  Some checks failed. This is normal if you don't use those features.

With Optional Tools Missing

IronClaw Doctor
===============

  [pass] NEAR AI session: API key configured
  [pass] Database backend: PostgreSQL connected
  [pass] Workspace directory: /Users/you/.ironclaw
  [skip] Docker: docker not found in PATH
  [skip] cloudflared: cloudflared not found in PATH
  [skip] ngrok: ngrok not found in PATH
  [skip] tailscale: tailscale not found in PATH

  3 passed, 0 failed

  Some checks failed. This is normal if you don't use those features.

Checks Explained

NEAR AI Session

Verifies authentication with NEAR AI:

Pass conditions:

• NEARAI_API_KEY environment variable is set, OR
• Session file exists at ~/.nearai/session and is readable

Fail conditions:

• No API key and no session file
• Session file exists but is empty
• Session file cannot be read

Fix:

ironclaw onboard
# Or
export NEARAI_API_KEY=your-api-key

Database Backend

Checks database connectivity:

PostgreSQL

Pass conditions:

• DATABASE_URL is set
• Can connect to the database
• SELECT 1 query succeeds

Fail conditions:

• DATABASE_URL not set
• Connection timeout (5s)
• Connection refused
• Authentication failure

Fix:

# Check DATABASE_URL
echo $DATABASE_URL

# Test connection
psql $DATABASE_URL -c "SELECT 1"

# Or run onboarding
ironclaw onboard

libSQL/Turso/SQLite

Pass conditions:

• Database file exists, OR
• Database will be created on first run

Info shown:

• Location of database file
• Whether it exists or will be created

Fix:

# Check path
echo $LIBSQL_PATH

# Verify directory exists and is writable
ls -la ~/.ironclaw/

# Create directory if needed
mkdir -p ~/.ironclaw

Workspace Directory

Verifies the base directory for IronClaw data:

Pass conditions:

• Directory exists and is readable
• Directory will be created on first run

Fail conditions:

• Path exists but is not a directory
• Permission denied

Fix:

# Create directory
mkdir -p ~/.ironclaw

# Fix permissions
chmod 700 ~/.ironclaw

Docker

Checks if Docker is available (required for sandboxed tool execution):

Pass conditions:

• docker binary found in PATH
• docker --version succeeds

Skip conditions:

• Docker not installed (normal if not using sandboxed tools)

Fail conditions:

• Docker installed but not responding
• Docker daemon not running

Fix:

# Install Docker
# macOS: https://docs.docker.com/desktop/install/mac-install/
# Linux: https://docs.docker.com/engine/install/

# Start Docker daemon
sudo systemctl start docker  # Linux
open -a Docker  # macOS

# Verify
docker --version

cloudflared

Checks if Cloudflare Tunnel client is available (for exposing webhooks):

Pass conditions:

• cloudflared binary found in PATH
• cloudflared --version succeeds

Skip conditions:

• Not installed (normal if not using Cloudflare Tunnels)

Fix:

# Install cloudflared
# macOS
brew install cloudflared

# Linux
wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

# Verify
cloudflared --version

ngrok

Checks if ngrok is available (for exposing webhooks):

Pass conditions:

• ngrok binary found in PATH
• ngrok version succeeds

Skip conditions:

• Not installed (normal if not using ngrok)

Fix:

# Install ngrok
# macOS
brew install ngrok/ngrok/ngrok

# Linux
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update && sudo apt install ngrok

# Verify
ngrok version

tailscale

Checks if Tailscale is available (for secure networking):

Pass conditions:

• tailscale binary found in PATH
• tailscale version succeeds

Skip conditions:

• Not installed (normal if not using Tailscale)

Fix:

# Install Tailscale
# macOS
brew install tailscale

# Linux
curl -fsSL https://tailscale.com/install.sh | sh

# Verify
tailscale version

When to Run Doctor

Run ironclaw doctor when:

1. After installation - Verify everything is set up correctly
2. Before first run - Check all dependencies
3. After configuration changes - Validate new settings
4. Troubleshooting - Diagnose issues
5. Before deploying - Ensure production readiness

Common Issues

”session file not found"

# Run onboarding
ironclaw onboard

# Or set API key
export NEARAI_API_KEY=your-key-here

"PostgreSQL connection failed"

# Check DATABASE_URL is set
echo $DATABASE_URL

# Test connection
psql $DATABASE_URL -c "SELECT 1"

# Check PostgreSQL is running
sudo systemctl status postgresql  # Linux
brew services list | grep postgresql  # macOS

"Docker not found”

Docker is optional. If you need it:

# Install Docker Desktop
# macOS: https://docs.docker.com/desktop/install/mac-install/
# Linux: https://docs.docker.com/engine/install/

“Permission denied” on workspace directory

# Fix permissions
chmod 700 ~/.ironclaw

# Verify
ls -la ~/.ironclaw

Exit Codes

• 0 - All critical checks passed
• 1 - One or more checks failed

Note: Skipped checks (optional binaries) do not affect the exit code.

Interpreting Results

Critical Failures

These must be fixed before using IronClaw:

• NEAR AI session
• Database backend
• Workspace directory

Optional Failures

These are only needed for specific features:

• Docker - Required for sandboxed WASM tool execution
• cloudflared - Only needed for Cloudflare Tunnel webhooks
• ngrok - Only needed for ngrok webhooks
• tailscale - Only needed for Tailscale networking

Automated Checks

Include doctor in your deployment scripts:

#!/bin/bash
set -e

# Run diagnostics
if ! ironclaw doctor; then
  echo "Doctor checks failed. Please fix issues before deploying."
  exit 1
fi

# Continue with deployment
echo "All checks passed. Deploying..."

CI/CD Integration

# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install IronClaw
        run: cargo install --path .
      - name: Run diagnostics
        env:
          DATABASE_URL: postgresql://test:test@localhost/test
          NEARAI_API_KEY: ${{ secrets.NEARAI_API_KEY }}
        run: ironclaw doctor

Related Commands

• onboard - Run initial configuration wizard
• config - View and modify settings
• service - Manage background service