ironclaw doctor - IronClaw

Overview

The ironclaw doctor command runs comprehensive diagnostic checks to validate your IronClaw installation. It actively probes external dependencies, tests database connectivity, and verifies configuration to surface issues before they cause problems during operation.

Unlike ironclaw status which provides passive status information, doctor performs active tests including network calls and binary checks.

Usage

ironclaw doctor

No options or arguments required.

Output

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

  [pass] NEAR AI session: session found (/home/user/.ironclaw/session.json)
  [pass] Database backend: PostgreSQL connected
  [pass] Workspace directory: /home/user/.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

  5 passed, 0 failed

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

Diagnostic Checks

NEAR AI Session

Validates authentication with NEAR AI:

Pass: Session file exists and is readable
Fail: Session file missing or empty

Pass output:

  [pass] NEAR AI session: session found (/home/user/.ironclaw/session.json)

Fail output:

  [FAIL] NEAR AI session: session file not found at /home/user/.ironclaw/session.json. Run `ironclaw onboard`

API key mode:

  [pass] NEAR AI session: API key configured

Database Backend

Tests database connectivity:

PostgreSQL: Attempts connection and executes SELECT 1
libSQL: Checks if database file exists or can be created

Pass output:

  [pass] Database backend: PostgreSQL connected

  [pass] Database backend: libSQL database exists (/home/user/.ironclaw/ironclaw.db)

Fail output:

  [FAIL] Database backend: PostgreSQL connection failed: connection refused

Workspace Directory

Verifies the workspace directory exists or can be created: Pass output:

  [pass] Workspace directory: /home/user/.ironclaw

  [pass] Workspace directory: /home/user/.ironclaw will be created on first run

Fail output:

  [FAIL] Workspace directory: /home/user/.ironclaw exists but is not a directory

Docker

Checks if Docker is installed and running: Pass output:

  [pass] Docker: Docker version 24.0.6, build ed223bc

Skip output:

  [skip] Docker: docker not found in PATH

Fail output:

  [FAIL] Docker: exited with error code 1

Docker is required for sandboxed code execution. If you don’t need code execution, it’s safe to skip this check.

cloudflared

Checks for Cloudflare Tunnel CLI: Pass output:

  [pass] cloudflared: cloudflared version 2024.2.1

Skip output:

  [skip] cloudflared: cloudflared not found in PATH

cloudflared is only needed if you want to expose your agent to the internet via Cloudflare Tunnels.

ngrok

Checks for ngrok tunnel client: Pass output:

  [pass] ngrok: ngrok version 3.5.0

Skip output:

  [skip] ngrok: ngrok not found in PATH

tailscale

Checks for Tailscale VPN client: Pass output:

  [pass] tailscale: 1.56.1

Skip output:

  [skip] tailscale: tailscale not found in PATH

Exit Codes

The doctor command always exits with code 0, even if some checks fail. This is intentional — not all checks are required for every use case.

Missing tunnel tools (cloudflared, ngrok, tailscale) are expected if you don’t need remote access
Missing Docker is acceptable if you don’t use code execution

Critical failures (database, session) should be addressed before running the agent.

Check Results

Three possible outcomes for each check:

Pass

  [pass] Check name: details

The check succeeded. Everything is working as expected.

Fail

  [FAIL] Check name: error details

The check failed. This may indicate a problem that needs attention.

Skip

  [skip] Check name: reason

The check was skipped (usually because the tool isn’t installed). This is often expected and not a problem.

Examples

First-time setup validation

After running ironclaw onboard, verify everything is configured:

ironclaw onboard
ironclaw doctor

Troubleshooting

If the agent isn’t starting:

ironclaw doctor

Look for [FAIL] results and address them.

Pre-deployment check

Before deploying to production:

ironclaw doctor > health-check.txt
cat health-check.txt

Verify all critical checks pass.

CI/CD pipeline

Add to your CI/CD pipeline:

#!/bin/bash
ironclaw doctor

# Check for critical failures
if ironclaw doctor | grep -q "\[FAIL\] NEAR AI session\|\[FAIL\] Database backend"; then
  echo "Critical checks failed!"
  exit 1
fi

Common Issues and Solutions

NEAR AI session not found

Problem:

[FAIL] NEAR AI session: session file not found

Solution:

ironclaw onboard

This will authenticate with NEAR AI and create the session file.

Database connection failed

Problem:

[FAIL] Database backend: PostgreSQL connection failed: connection refused

Solution:

Check that PostgreSQL is running:
pg_isready
Verify DATABASE_URL is correct:
echo $DATABASE_URL
Test connection manually:
psql $DATABASE_URL -c "SELECT 1"

Or switch to libSQL:

export DATABASE_BACKEND=libsql
ironclaw doctor

Docker not found

Problem:

[skip] Docker: docker not found in PATH

Solution (if you need Docker):macOS:

brew install --cask docker

Linux:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Skip this check if you don’t need code execution features.

Workspace directory is not a directory

Problem:

[FAIL] Workspace directory: /home/user/.ironclaw exists but is not a directory

Solution: The workspace path is occupied by a file. Remove it:

rm ~/.ironclaw
mkdir ~/.ironclaw

Or choose a different path:

export IRONCLAW_HOME=/path/to/workspace
ironclaw doctor

What Gets Checked

Configuration Checks

NEAR AI authentication (session file or API key)
Database backend (PostgreSQL or libSQL)
Workspace directory

External Binary Checks

Docker (for code execution)
cloudflared (for Cloudflare Tunnels)
ngrok (for ngrok tunnels)
tailscale (for Tailscale VPN)

Not Checked

WASM tools (use ironclaw tool list)
MCP servers (use ironclaw mcp list)
Settings values (use ironclaw config list)
Service status (use ironclaw service status)

Status vs Doctor

Two commands provide health information:

Feature	`ironclaw status`	`ironclaw doctor`
Speed	Fast	Slower
Network calls	No	Yes
Binary checks	No	Yes
Database probe	Passive	Active
Use case	Monitoring	Troubleshooting

Use status for quick checks. Use doctor for thorough diagnostics.

ironclaw status

Quick health check

ironclaw onboard

Fix configuration issues

ironclaw config list

View all settings

​Overview

​Usage

​Output

​Diagnostic Checks

​NEAR AI Session

​Database Backend

​Workspace Directory

​Docker

​cloudflared

​ngrok

​tailscale

​Exit Codes

​Check Results

​Pass

​Fail

​Skip

​Examples

​First-time setup validation

​Troubleshooting

​Pre-deployment check

​CI/CD pipeline

​Common Issues and Solutions

​What Gets Checked

​Configuration Checks

​External Binary Checks

​Not Checked

​Status vs Doctor

​Related Commands

ironclaw status

ironclaw onboard

ironclaw config list

Overview

Usage

Output

Diagnostic Checks

NEAR AI Session

Database Backend

Workspace Directory

Docker

cloudflared

ngrok

tailscale

Exit Codes

Check Results

Pass

Fail

Skip

Examples

First-time setup validation

Troubleshooting

Pre-deployment check

CI/CD pipeline

Common Issues and Solutions

What Gets Checked

Configuration Checks

External Binary Checks

Not Checked

Status vs Doctor

Related Commands