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

# Basic health check
coi health

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

# Verbose output with additional checks
coi health --verbose

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

SYSTEM:
  [OK]   Operating system  : Ubuntu 24.04.4 LTS (amd64)
  [OK]   Kernel version    : Kernel 6.17.0-19-generic (>= 5.15)

CRITICAL:
  [OK]   Incus             : Running (version 6.21)
  [OK]   Permissions       : User in incus-admin group
  [OK]   Default image     : coi-default (fingerprint: 3c946d37f573)
  [OK]   Image age         : 2 days old
  [OK]   Privileged check  : Default profile uses unprivileged containers
  [OK]   Security posture  : Full isolation - unprivileged containers with seccomp and AppArmor

NETWORKING:
  [OK]   Network bridge    : incusbr0 (10.128.178.1/24)
  [OK]   IP forwarding     : Enabled
  [OK]   nft firewall      : nft available, Incus bridge NAT enabled (restricted mode available)
  [OK]   Bridge forward    : Bridge incusbr0 forwarding OK
  [OK]   Docker FORWARD    : Docker running, FORWARD policy is not DROP

MONITORING:
  [OK]   nftables          : Available and configured
  [OK]   systemd journal   : Access granted
  [OK]   libsystemd        : Installed

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

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

STATUS:
  [OK]   Containers        : 1 running
  [OK]   Saved sessions    : 12 session(s)
  [OK]   Orphaned resources: No orphaned resources

OTHER:
  [OK]   Monitoring config : Enabled with auto_pause=true
  [OK]   Audit Log Dir     : ~/.coi/audit (writable)
  [OK]   Cgroup Availability: Cgroup v2 is available with controllers
  [OK]   Container Connectivity: DNS and HTTP working (status 200)
  [OK]   Network Restriction: Restricted mode working (external OK, private networks blocked)

STATUS: HEALTHY
All 27 checks passed

Note: The MONITORING section (nftables, systemd journal, libsystemd) only appears when monitoring.nft.enabled = true in your config. The --verbose flag adds optional checks like DNS resolution, passwordless sudo, and process monitoring capability.

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

The Security posture check inspects the default Incus profile to verify container isolation:

JSON output (--format json) includes detailed fields: seccomp, apparmor, privileged, raw_seccomp_override, raw_apparmor_override.

COI enforces minimum versions for critical dependencies:

• Incus >= 6.1 - Required for UID mapping support. coi health warns; coi shell/coi run/coi build fail with an actionable error and a link to install from the Zabbly repository.
• nftables >= 0.9.0 - Required for network monitoring features. coi health warns if below minimum.
• Kernel >= 5.15 - Recommended for security features. coi health and CLI commands warn on stderr but do not block.

coi health --format json

Returns structured JSON with all check results, suitable for scripting and CI integration:

{
  "status": "healthy",
  "timestamp": "2026-03-29T12:00:00Z",
  "checks": {
    "security_posture": {
      "name": "security_posture",
      "status": "ok",
      "message": "Full isolation - unprivileged containers with seccomp and AppArmor",
      "details": {
        "seccomp": "enabled (default)",
        "apparmor": "enabled (default)",
        "privileged": false,
        "raw_seccomp_override": false,
        "raw_apparmor_override": false
      }
    }
  },
  "summary": {
    "total": 27,
    "passed": 27,
    "warnings": 0,
    "failed": 0
  }
}

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 nft is not available or passwordless sudo is not configured, the nft check provides Colima-specific guidance (set mode = "open"). AppArmor is not available in Lima VMs, so the security posture check reports seccomp-only isolation.

Privileged profile detection: If security.privileged=true is set on the default Incus profile, both the privileged_profile and security_posture checks will fail. Fix with: incus profile unset default security.privileged

# Update to the latest release
coi update

# Check for updates without installing
coi update core --check

# Skip confirmation prompt
coi update --force

1. Queries the GitHub releases API for the latest release
2. Compares the current version against the latest semantic version
3. Downloads the platform-appropriate binary (e.g., coi-linux-amd64)
4. Verifies the SHA256 checksum against the published checksums.txt
5. Atomically replaces the current binary (temp file + rename)

Checksum verification — Downloaded binary is verified against the SHA256 checksum before replacing the current binary.

Symlink-aware — If coi is a symlink, the symlink is resolved before replacing so existing symlinks continue working.

Sudo auto-escalation — When the binary directory is not writable by the current user (e.g., /usr/local/bin), COI automatically re-executes with sudo.

Dev build safety — Development builds (no version tag) print a warning and require --force to update.

After a coi update, run a health check to verify the environment is still correctly configured:

coi health

If the release notes mention image changes, rebuild the container image:

coi build --force

• Troubleshooting - Detailed diagnosis steps for specific issues
• Image Management - Rebuilding images to fix environment issues
• Security Monitoring - Verifying monitoring is active and healthy