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

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

```bash theme={null}
# Run all diagnostics
ironclaw doctor
```

## Output

### Successful Run

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

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

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

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

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

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

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

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

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

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

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

```bash theme={null}
# Run onboarding
ironclaw onboard

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

### "PostgreSQL connection failed"

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

```bash theme={null}
# Install Docker Desktop
# macOS: https://docs.docker.com/desktop/install/mac-install/
# Linux: https://docs.docker.com/engine/install/
```

### "Permission denied" on workspace directory

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

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

```yaml theme={null}
# .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](/cli/onboard) - Run initial configuration wizard
* [config](/cli/config) - View and modify settings
* [service](/cli/service) - Manage background service