Run full system diagnostics.

nself doctor [flags]

nself doctor checks everything ɳSelf needs to function correctly and reports issues with actionable fix suggestions. It covers infrastructure prerequisites (Docker, Docker Compose, Git), Docker daemon health and permissions, disk and memory availability, network connectivity, configuration correctness, running container health, and plugin schema placement.

Run nself doctor when something is not working as expected, before deploying to a new environment, or as part of an automated health check pipeline. The --fix flag enables automatic remediation of common problems.

The --deep flag runs all 12 subsystem checks including open port analysis, weak cipher detection, exposed service bindings, container-level security, and a CIS container benchmark subset. The deep scan runs without a license key: all hardening checks are free by design.

CRITICAL findings include: world-readable secret files, sensitive ports bound on 0.0.0.0, missing JWT secrets, and weak SSL cipher suites. These indicate an immediate security risk and must be resolved before the service is considered safe to run.

Fires during nself doctor --deep in the ai-safety section.

What it checks: If the ai plugin is loaded AND the deployment binds on a non-loopback address (e.g., 0.0.0.0) AND the moderation plugin is NOT loaded, emit a WARN.

Self-hosted single-user deployments on loopback are explicitly exempted, this is a legitimate use case.

Fix:

nself plugin install moderation
nself build && nself start

The check reads NSELF_AI_LOADED, PLUGIN_AI_INTERNAL_URL, NSELF_MODERATION_LOADED, PLUGIN_MODERATION_INTERNAL_URL, and NSELF_BIND_ADDRESS from the environment.

Detection fixture:

nself doctor --deep --config-file test/fixtures/ai-public-no-mod.env
# Emits: "moderation not wired on public-bound deployment with ai loaded"

Fires during nself doctor --deep in the performance section.

What it checks: Total configured pgxpool MaxConns across all active services must not exceed POSTGRES_MAX_CONNECTIONS. Default Postgres ships with max_connections=100. With 23 enabled services at the default cap of 10 connections each, total = 230, exceeding the limit causes random 503 errors under load.

Recommended cap formula: min(10, floor(postgres_max_connections / num_active_services))

Fix: Raise POSTGRES_MAX_CONNECTIONS in .env or reduce per-plugin pool size. The check emits a FixCmd suggestion with the exact value to set.

# Skip the pool sizing check (not recommended in production)
nself doctor --deep --skip-pool

Fires during nself doctor --deep in the security section.

What it checks:

1. For every np_* table: pg_class.relrowsecurity = true (RLS enabled) and at least one policy exists.
2. For every np_* table with a tenant_id column: pg_class.relforcerowsecurity = true (FORCE RLS, prevents table owner from bypassing policies).
3. For every np_* table with a tenant_id column: Hasura metadata has a select permission for the user role with a tenant_id row filter ({"tenant_id": {"_eq": "X-Hasura-Tenant-Id"}}).

Security-Always-Free Doctrine: this check runs without a license key.

Violation output format:

RLS-DISABLED table=np_chat_messages
RLS-FORCE-MISSING table=np_claw_cost_events role=user
HASURA-FILTER-MISSING table=np_claw_cost_events role=user

Env vars read:

• NSELF_DB_URL or DATABASE_URL, Postgres connection string
• HASURA_GRAPHQL_URL, Hasura endpoint (default: http://127.0.0.1:8080)
• HASURA_GRAPHQL_ADMIN_SECRET, required for Hasura metadata query; if absent, Hasura filter check is skipped with a warning

Fix:

# Fix missing FORCE RLS on a table
nself migrate apply --rls-force np_chat_messages

# Re-run the check after fixing
nself doctor --deep --only security

See also: multi-tenant conventions for the canonical wall doc on source_account_id vs tenant_id.

Fires during nself doctor (standard and deep) in the Configuration section.

What it checks: If POSTGRES_USER equals the default value postgres and NSELF_ENV is prod or staging, the check emits a WARN. The default is appropriate for dev; in production it is a predictable attack surface.

This does not change the default or block deployment — it is an advisory warning only.

Fix: Set POSTGRES_USER=<unique-name> in your .env before nself build:

# .env
POSTGRES_USER=myprod_db_user

Then rebuild: nself build && nself start.

nself doctor --install-check runs a focused readiness check that maps to the 6-stage onboarding funnel. It is invoked automatically by the Homebrew post_install hook after brew install nself. You can also run it manually at any time.

$ nself doctor --install-check

Onboarding Funnel Check
  Stage 1 — Install       v1.1.1 (darwin/arm64)
  Stage 2 — Activation    2 projects initialized
  Stage 3 — First-use     first start 3 days ago
  Stage 4 — First-plugin  no plugins installed
    → Run: nself plugin install ai  (or any plugin)
  Stage 5 — First-value   (skipped, prior stage failed)
  Stage 6 — Habit         (skipped, prior stage failed)

Funnel position: Stage 3/6. Next: nself plugin install ai  (or any plugin)

Each stage prints PASS, FAIL, UNKNOWN, or SKIPPED:

Stage 5 shows UNKNOWN (not FAIL) when the query-count file is absent. This avoids penalising self-hosters who have not wired the optional Hasura telemetry hook.

Pass --json for machine-readable output:

nself doctor --install-check --json

Exit codes: 0 = all 6 stages pass; 1 = one or more stages fail.

nself doctor --check-legacy scans the host machine for stale v0.9 global paths that persist after migration:

For each path found, the output shows the path, its type, and a cleanup hint. The check is read-only: it never deletes anything automatically.

$ nself doctor --check-legacy
WARNING: Found 2 v0.9 stale artifact(s) on this host:
  [dir]  /Users/me/.nself  — safe to remove: rm -rf ~/.nself (after verifying no custom config)
  [file] /usr/local/share/nself  — safe to remove: sudo rm -f /usr/local/share/nself

Run the cleanup commands above, then re-run `nself doctor --check-legacy` to confirm.

If no stale paths are found, the command exits 0 with No v0.9 global artifacts detected. Clean install.

This flag exits early without running any other doctor checks. Combine with other checks by running them separately.

When --json is passed, the command writes a single JSON object to stdout and produces no other output. The JSON schema is:

{
  "timestamp": "2026-04-17T12:00:00Z",
  "checks": [
    {
      "name": "[security] Exposed port 5432 (Postgres)",
      "status": "critical",
      "message": "Postgres port 5432 is bound on 0.0.0.0 — bind to 127.0.0.1",
      "detail": "docker stop nself_postgres && nself build && nself start"
    }
  ],
  "summary": {
    "total": 42,
    "passed": 39,
    "warnings": 1,
    "failed": 1,
    "critical": 1
  }
}

Status values: pass, warn, fail, critical.

# Quick diagnostic
nself doctor

# Full diagnostic (includes network and memory checks)
nself doctor --full

# Full hardening scan across all 12 subsystems
nself doctor --deep

# Deep scan, one subsystem only
nself doctor --deep --only security

# Verbose output with details per check
nself doctor --verbose

# JSON output for automated monitoring
nself doctor --json

# Auto-fix safe issues
nself doctor --fix

# Deep scan with JSON output, useful for CI security gates
nself doctor --deep --json

# First-run AI wizard (installs Ollama, sets up Gemini pool)
nself doctor --ai

# First-run AI wizard, non-interactive
nself doctor --ai --yes

← Commands | Home →