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.

You don’t need to understand the technical details to use this feature. The configuration examples below are copy-paste ready.

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 for platform details.

Install with npm

1. Install and verify the CLI

   npm install -g comisai
   comis --version
   

   The second command prints the version you installed.

2. Run the setup wizard

   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.

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

4. Start and verify the daemon

   If you did not start it from the wizard, run:

   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.

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

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:

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:

comis init --non-interactive --accept-risk \
  --provider anthropic \
  --api-key "$ANTHROPIC_API_KEY" \
  --agent-name "assistant" \
  --storage encrypted

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.

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:

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

Connect a Channel

Configure one of the ten documented messaging adapters.

Security Boundaries

Understand defaults, optional controls, and deployment limitations.

Operations

Run, monitor, back up, and troubleshoot the daemon.

CLI Reference

Review every current command group and flag.