Verify Your Installation

Confirm that Comis is installed correctly and running as expected

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:

comis 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:

comis 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:

curl http://localhost:4766/health

Expected response:

{ "status": "ok" }

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:

comis doctor

The doctor currently covers ten subsystems:

Category	What it verifies
Configuration and version skew	Schema validity and package compatibility
Daemon and gateway	Process and local API health
Channels and Teams	General channel checks and Teams-specific health
Workspace and LCD	Workspace plus lossless context/session storage
OAuth and secrets audit	Credential-profile health and plaintext exposure

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:

comis security audit

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

Check	What It Verifies	Common Fix
Config	YAML syntax, required fields	Run comis config validate for details
Daemon	Background process is running	Run comis daemon start
Gateway	HTTP server listening on port	Check port 4766 availability
Channel	Platform configuration and connectivity	Update the named secret with comis secrets set or the configured external secret source
Workspace	File permissions, data directory	Run comis doctor --repair

Common problems

Daemon not starting

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/

Gateway not responding

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

Config parse error

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

Channel disconnected

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

Permission denied on data directory

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.