nkapp doctor

Run a comprehensive environment health check to verify that all prerequisites are met and the local Nanokit installation is correctly configured.

nkapp doctor

doctor is a zero-argument command — just run it in the root of any Nanokit project (or without a project for system-level checks).

What It Checks

doctor runs these diagnostic categories in order:

1. System Architecture

Reads the host OS and CPU architecture. Nanokit officially supports x64 and arm64 (Apple Silicon / AWS Graviton). A warning is emitted for any other architecture but execution continues.

2. Docker Health

Pings the local Docker daemon and prints the engine version and operating system.

[!TIP] If Docker is not found, install Docker Desktop  or run sudo systemctl start docker on Linux.

3. Configuration Audit

Locates nanokit.yml in the current directory and parses it against the local environment to validate syntax and schema. Errors here indicate YAML formatting issues or unknown configuration keys.

4. Infrastructure Status

Queries the local Docker provider for any running containers tagged with the current project name and environment. Reports whether the Gateway container is active, which is required for routing traffic to local services.

5. Mail Delivery

If your project configures mail (a mail: block), doctor reports the mail delivery mode per environment and validates it against the target provider’s capabilities. Silent when mail is not configured.

6. CLI Version

Reports whether your CLI is up to date, using the update-notifier cache (no extra network call). Warns if a newer @nkapp/cli is available (run nkapp update).

Example Output

  Nanokit Doctor - Environment Health Check

  ℹ System: linux (x64)
  ✓ Architecture is fully supported.

  Docker Health
  ✓ Docker Engine is running.
    Version: 24.0.7
    Operating System: Docker Desktop

  Configuration Audit
  ✓ nanokit.yml is valid.

  Infrastructure Status
  ✓ Local Gateway is active.

  Diagnosis Summary
  ✓ All systems go! Your Nanokit environment is healthy.

Exit Behaviour

doctor always exits 0, even when errors are detected, so it can be safely included in scripts without breaking downstream steps. Inspect the printed summary to decide whether to proceed.

[!NOTE] Run nkapp doctor whenever you encounter unexpected behaviour after installing Nanokit, updating Docker, or switching machines. It is the fastest way to rule out environment configuration issues.