Skip to main content
After installing and configuring Comis, run these checks to make sure everything is working.
You don’t need to understand the technical details to use this feature. The configuration examples below are copy-paste ready.

​
Quick health check

Run these checks in order. A passing gateway check does not prove that every provider, channel, or security control is configured; use comis doctor for the broader assessment. Check 1 — CLI health:
By default, this command shows health issues. Use comis health --all to include passing checks, or --format json for automation. Check 2 — System status:
Confirm that the daemon and gateway are online and that the expected agents and channels are listed. Exact fields depend on the configuration. Check 3 — Gateway endpoint:
Expected response:
If all three checks pass, the core local path is responding. Open http://localhost:4766 in your browser to start chatting with your agent.

​
Full diagnostic

For a comprehensive check across all subsystems, run the doctor command:
The doctor currently covers ten subsystems: Use comis doctor --format json for machine-readable output. A failing check includes a remediation hint.
If doctor finds fixable issues, run comis doctor --repair to attempt automatic fixes. The repair mode handles common problems like stale PID files, incorrect file permissions, and missing directories.

​
Security audit

Run a security check to verify your installation follows best practices:
The audit reports findings at critical, warning, and info severity.
For details on each security check and how to resolve findings, see Security: Audit.

​
What each check means

​
Common problems

Symptom: comis daemon start fails or the daemon exits immediately.Fix:
  1. Check the daemon logs: comis daemon logs
  2. Verify your config is valid: comis config validate
  3. Make sure no other process is using port 4766
  4. Check file permissions on ~/.comis/
Symptom: curl http://localhost:4766/health returns “connection refused.”Fix:
  1. Confirm the daemon is running: comis daemon status
  2. Check that the gateway is enabled in config (it is enabled by default)
  3. Verify the correct port: check gateway.port in your config
  4. If running in Docker, ensure the host is set to 0.0.0.0
Symptom: Daemon fails to start with a configuration error message.Fix:
  1. Run comis config validate to see the exact error with line number
  2. Common YAML issues: incorrect indentation, missing quotes around special characters, tabs instead of spaces
  3. Verify all ${VAR} references resolve through comis secrets list or the configured external secret source
Symptom: comis doctor reports a channel check failure.Fix:
  1. Verify the named bot token is available through the active secret backend
  2. Check that the bot has not been deactivated on the platform
  3. Confirm network connectivity to the platform API
  4. For Telegram: make sure the bot token is from @BotFather
Symptom: Errors mentioning EACCES or permission denied for paths under ~/.comis/.Fix:
  1. Run comis doctor --repair to fix common permission issues
  2. Manually fix ownership: sudo chown -R $(whoami) ~/.comis
  3. Check that ~/.comis/ has mode 700: ls -ld ~/.comis

​
Getting help

If the checks above do not resolve your issue:
  • Troubleshooting — detailed solutions for common problems organized by category
  • FAQ — answers to frequently asked questions
  • GitHub Issues — report a bug or search for known issues

​
Next steps

Troubleshooting

Detailed solutions for common problems.

FAQ

Answers to frequently asked questions.

Connect a Channel

Add Telegram, Discord, Slack, and more.

Configuration Guide

Customize your agent settings and advanced options.