> ## Documentation Index
> Fetch the complete documentation index at: https://comis-fix-skill-import-vetting-gate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  You don't need to understand the technical details to use this feature. The configuration examples below are copy-paste ready.
</Info>

## 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:**

```bash theme={}
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:**

```bash theme={}
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:**

```bash theme={}
curl http://localhost:4766/health
```

Expected response:

```json theme={}
{ "status": "ok" }
```

<Tip>
  If all three checks pass, the core local path is responding. Open
  `http://localhost:4766` in your browser to start chatting with your agent.
</Tip>

## Full diagnostic

For a comprehensive check across all subsystems, run the doctor command:

```bash theme={}
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.

<Info>
  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.
</Info>

## Security audit

Run a security check to verify your installation follows best practices:

```bash theme={}
comis security audit
```

The audit reports findings at `critical`, `warning`, and `info` severity.

<Info>
  For details on each security check and how to resolve findings, see
  [Security: Audit](/security/audit).
</Info>

## 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

<AccordionGroup>
  <Accordion title="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/`
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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](https://t.me/BotFather)
  </Accordion>

  <Accordion title="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`
  </Accordion>
</AccordionGroup>

## Getting help

If the checks above do not resolve your issue:

* **[Troubleshooting](/operations/troubleshooting)** -- detailed solutions for
  common problems organized by category
* **[FAQ](/operations/faq)** -- answers to frequently asked questions
* **[GitHub Issues](https://github.com/comisai/comis/issues)** -- report a bug or
  search for known issues

## Next steps

<CardGroup cols={2}>
  <Card title="Troubleshooting" icon="wrench" href="/operations/troubleshooting">
    Detailed solutions for common problems.
  </Card>

  <Card title="FAQ" icon="circle-question" href="/operations/faq">
    Answers to frequently asked questions.
  </Card>

  <Card title="Connect a Channel" icon="messages" href="/channels/index">
    Add Telegram, Discord, Slack, and more.
  </Card>

  <Card title="Configuration Guide" icon="gear" href="/installation/configuration">
    Customize your agent settings and advanced options.
  </Card>
</CardGroup>