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 three commands in order. If all three pass, your installation is healthy.

Check 1 — CLI health:

comis health

Expected output when everything is working:

All checks passed

If there are issues, you will see them listed by category with suggested fixes.

Check 2 — System status:

comis status

Expected output:

  Daemon
  Status    online
  Uptime    2m 30s

  Gateway
  Status    online
  Address   127.0.0.1:4766

  Channels
  No channels configured

  Agents
  Name      Provider    Model                        Bindings
  default   anthropic   claude-sonnet-4-5-20250929     -

Check 3 — Gateway endpoint:

curl http://localhost:4766/health

Expected response:

{ "status": "ok" }

If all three checks pass, your installation is healthy. 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 runs checks in five categories:

Category	What it verifies
Config	YAML syntax, required fields, valid provider settings
Daemon	Background process is running and responsive
Gateway	HTTP server is listening on the configured port
Channel	Connectivity for each configured channel
Workspace	File permissions, data directory structure

Expected output when all checks pass:

  Category     Status   Details
  Config       pass     Configuration is valid
  Daemon       pass     Daemon is running (PID: 12345)
  Gateway      pass     Gateway listening on 127.0.0.1:4766
  Channel      pass     No channels configured
  Workspace    pass     Data directory OK

If a check fails, the output includes the specific error and a suggested fix:

  Category     Status   Details
  Config       pass     Configuration is valid
  Daemon       pass     Daemon is running (PID: 12345)
  Gateway      fail     Gateway not responding on 127.0.0.1:4766
                        → Check if port 4766 is available
  Channel      pass     No channels configured
  Workspace    pass     Data directory OK

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 runs all checks and reports findings by severity: critical, high, medium, and low.

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 bot tokens are valid	Re-enter token in config or .env
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 have matching entries in your .env file

Channel disconnected

Symptom: comis doctor reports a channel check failure.

Fix:

1. Verify the bot token is correct in your .env file
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.