Skip to content

System Health Check

Jump to bottom
Maciej Mensfeld edited this page Feb 24, 2026 · 3 revisions

Use coi health to diagnose setup issues and verify your environment is correctly configured.

Usage

# Basic health check
coi health

# JSON output for scripting/automation
coi health --format json

# Verbose output with additional checks
coi health --verbose

Example Output

Code on Incus Health Check
==========================

SYSTEM:
  [OK]   Operating system   Ubuntu 24.04.3 LTS (amd64)

CRITICAL:
  [OK]   Incus              Running (version 6.20)
  [OK]   Permissions        User in incus-admin group
  [OK]   Default image      coi (fingerprint: 1bf24b3a67...)
  [OK]   Image age          2 days old

NETWORKING:
  [OK]   Network bridge     incusbr0 (10.128.178.1/24)
  [OK]   IP forwarding      Enabled
  [OK]   Firewalld          Running (restricted mode available)

STORAGE:
  [OK]   COI directory      ~/.coi (writable)
  [OK]   Sessions dir       ~/.coi/sessions-claude (writable)
  [OK]   Disk space         455.0 GB available
  [OK]   Incus storage pool Pool 'default': 26.1 GiB free of 50.0 GiB (48% used)

CONFIGURATION:
  [OK]   Config loaded      ~/.config/coi/config.toml
  [OK]   Network mode       restricted
  [OK]   Tool               claude

STATUS:
  [OK]   Containers         1 running
  [OK]   Saved sessions     12 session(s)

MONITORING:
  [OK]   nftables           Available and configured
  [OK]   systemd journal    Access granted
  [OK]   libsystemd         Installed
  [OK]   Monitoring config  Enabled
  [OK]   Audit log dir      ~/.coi/audit (writable)
  [OK]   Cgroup availability Available

CONTAINER NETWORKING:
  [OK]   Container connectivity External network OK (api.anthropic.com)
  [OK]   Network restriction    Restricted mode working

STATUS: HEALTHY
All 24 checks passed

Exit Codes

  • 0 = healthy (all checks pass)
  • 1 = degraded (warnings but functional)
  • 2 = unhealthy (critical failures)

What's Checked

Category Checks
System OS info, Colima/Lima detection
Critical Incus availability, group permissions, default image, image age
Networking Network bridge, IP forwarding, firewalld (mode-aware)
Storage COI directory, sessions directory, disk space (warns if <5GB), Incus storage pool (warns if <5GB free or >80% used, fails if <2GB free or >90% used)
Configuration Config files, network mode, tool
Status Running containers, saved sessions, orphaned resources
Monitoring nftables, systemd-journal access, libsystemd, monitoring config, audit log directory, cgroup availability
Container Networking Container connectivity (DNS + HTTP), network restriction verification
Optional DNS resolution, passwordless sudo, process monitoring capability (with --verbose)

Notes

Colima/Lima detection: When running inside a Colima or Lima VM, the health check automatically detects this and shows [colima] in the OS info. If firewalld is not available, it provides Colima-specific guidance.

Clone this wiki locally