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

# Quickstart

> Install Comis, configure an agent, and verify your first conversation

This guide installs Comis, walks through the current setup wizard, and verifies
that the daemon and web dashboard work.

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

## Before you begin

Choose one runtime:

* **npm:** macOS or Linux with Node.js **22.19.0 or newer**, npm, Python 3,
  and native build tools.
* **Docker:** Docker Engine 24 or newer with Docker Compose v2. Use a Linux
  Docker host for production; Docker Desktop on macOS or Windows does not
  provide the same shell-isolation boundary.

Choose one model-provider path:

* an API key for a supported provider;
* an OAuth login for a subscription-backed provider such as `openai-codex`; or
* a supported local provider such as Ollama, which requires no hosted-provider
  credential.

See [Requirements](/installation/requirements) for platform details.

## Install with npm

<Steps>
  <Step title="Install and verify the CLI">
    ```bash theme={}
    npm install -g comisai
    comis --version
    ```

    The second command prints the version you installed.
  </Step>

  <Step title="Run the setup wizard">
    ```bash theme={}
    comis init
    ```

    The wizard is staged rather than a three-question prompt. Depending on the
    flow and provider you choose, it covers:

    1. quick or advanced setup;
    2. credential storage;
    3. model provider and API-key, OAuth, or local-provider setup;
    4. agent identity and model;
    5. optional messaging channels;
    6. gateway access and workspace settings;
    7. optional web-search, media, voice, and recall providers;
    8. a review screen, configuration write, and optional daemon start.

    You can skip optional integrations and add them later.
  </Step>

  <Step title="Back up the master key">
    New setups default to `security.storage: encrypted`. The wizard stores
    collected credentials in `~/.comis/secrets.db` and writes the
    `SECRETS_MASTER_KEY` to `~/.comis/.env` with owner-only permissions.

    Back up `~/.comis/.env` to a secure location. Comis has no key escrow:
    losing the master key makes the encrypted credential database unreadable.
    Encryption protects a copied database from someone who does not also have
    the key; it does not protect against a compromised host that can read both.
  </Step>

  <Step title="Start and verify the daemon">
    If you did not start it from the wizard, run:

    ```bash theme={}
    comis daemon start
    comis doctor
    comis status
    ```

    `doctor` reports configuration and runtime checks. Treat configured but
    untested integrations as unverified until their platform-specific check
    succeeds.
  </Step>

  <Step title="Open the dashboard">
    Open `http://localhost:4766` on the same machine and send a test message.
    The gateway binds to loopback by default; do not expose it publicly without
    authentication and TLS. See [Hardening](/security/hardening).
  </Step>
</Steps>

## Provider choices

### API-key providers

Choose the provider in the wizard and enter the key at the hidden prompt. The
encrypted-store default keeps the provider key out of `config.yaml` and out of
plaintext `.env` entries.

### OpenAI Codex OAuth

Choose `openai-codex` for ChatGPT/Codex subscription authentication. On a local
desktop, use the browser flow. On an SSH or headless host, use device code:

```bash theme={}
comis auth login --provider openai-codex --method device-code
```

If you skip login during setup, run that command before starting the agent.
OAuth login is interactive and therefore is not a valid
`comis init --non-interactive` provider path.

### Local providers

Choose a supported local provider such as Ollama and make sure its service is
running before validation. No hosted-provider API key is required.

## Non-interactive setup

For automation, pass non-secret settings as arguments and source secret values
from protected environment variables:

```bash theme={}
comis init --non-interactive --accept-risk \
  --provider anthropic \
  --api-key "$ANTHROPIC_API_KEY" \
  --agent-name "assistant" \
  --storage encrypted
```

<Warning>
  Command-line arguments can be visible in shell history and process listings.
  Even when the value comes from an environment variable, `--api-key` places the
  expanded value in the process arguments. Prefer the interactive wizard for
  human-operated hosts. Use non-interactive secret flags only in a controlled
  automation environment with protected logs and process access.
</Warning>

Run `comis init --help` for the authoritative list of non-interactive flags.
`openai-codex` cannot be initialized non-interactively; initialize with another
provider or local configuration, then complete OAuth from a TTY.

## Docker quick path

The published image can run without host Node.js. Initialize the persistent
volume in a one-shot container first; when the wizard asks whether to start the
daemon, choose **No** because the long-running container starts it in the next
command:

```bash theme={}
docker volume create comis-data

docker run --rm -it \
  -v comis-data:/home/comis/.comis \
  comisai/comis:latest-slim \
  comis init

docker run -d \
  --name comis \
  --restart unless-stopped \
  -p 127.0.0.1:4766:4766 \
  -v comis-data:/home/comis/.comis \
  comisai/comis:latest-slim

curl http://127.0.0.1:4766/health
```

Use a pinned release tag, a Linux host, persistent storage, gateway
authentication, and TLS for a production deployment. See
[Install with Docker](/installation/install-docker) for the complete setup.

## Add a channel

The web dashboard works without a messaging channel. To add one later, re-run
`comis init` and choose the channel stage, or follow the relevant
[channel guide](/channels/index). Comis documents ten channel adapters:
Discord, Telegram, Slack, WhatsApp, Signal, iMessage, LINE, IRC, Email, and
Microsoft Teams.

## Useful commands

| Command                       | Purpose                                       |
| ----------------------------- | --------------------------------------------- |
| `comis daemon status`         | Check the daemon process                      |
| `comis daemon logs -f`        | Follow daemon logs                            |
| `comis doctor`                | Diagnose configuration and runtime subsystems |
| `comis status`                | Show the current system overview              |
| `comis security audit`        | Review security findings                      |
| `comis secrets audit --check` | Detect plaintext credential exposure          |

## Next steps

<CardGroup cols={2}>
  <Card title="Connect a Channel" icon="messages" href="/channels/index">
    Configure one of the ten documented messaging adapters.
  </Card>

  <Card title="Security Boundaries" icon="shield-check" href="/get-started/security">
    Understand defaults, optional controls, and deployment limitations.
  </Card>

  <Card title="Operations" icon="gauge" href="/operations/index">
    Run, monitor, back up, and troubleshoot the daemon.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/reference/cli">
    Review every current command group and flag.
  </Card>
</CardGroup>