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 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
Description
The doctor command performs a series of checks to verify:
- Authentication - NEAR AI session or API key
- Database - Database backend connectivity
- Workspace - Directory existence and permissions
- 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.
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 PATHdocker --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 PATHcloudflared --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 PATHngrok 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 PATHtailscale 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:
- After installation - Verify everything is set up correctly
- Before first run - Check all dependencies
- After configuration changes - Validate new settings
- Troubleshooting - Diagnose issues
- 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 passed1 - 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
- onboard - Run initial configuration wizard
- config - View and modify settings
- service - Manage background service