Quickstart

Get your first Comis agent running in under 5 minutes

This guide takes you from zero to a working AI agent. By the end, you will have Comis installed, configured with your AI provider, and chatting with your first agent through the web dashboard.

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

Prerequisites

Before you begin, make sure you have:

• An API key from an AI provider (Anthropic, OpenAI, or Google). You will need this during setup.
• A terminal (command line) — Terminal on macOS, or any Linux shell.
• One of:
  • Node.js 22 or later — check with node --version. Install at nodejs.org. Pick this if you want to install Comis directly on your machine or extend it from source.
  • Docker Engine 20.10 or later — check with docker --version. Install at docker.com/get-started. Pick this if you would rather not install Node.js or you are running on a server.

Install and run

npm (recommended)

Run Comis directly on your machine. Best if you already have Node.js or plan to develop against the source.

1. Install Comis

   Open your terminal and install Comis globally with npm:

   npm install -g comisai
   

   Once the installation finishes, verify it worked:

   comis --version
   

   You should see the installed version, for example:

   1.0.42
   

   If you get a “permission denied” error, you may need to run sudo npm install -g comisai or configure npm to use a different directory. See Installation Details for alternatives.

2. Run the setup wizard

   Run the interactive setup wizard:

   comis init
   

   The wizard walks you through three simple questions:

   1. Which AI provider? — Choose from Anthropic (Claude), OpenAI (GPT), Google (Gemini), and others. Pick whichever provider you have an API key for.
   2. Your API key — Paste the API key from your chosen provider. The wizard stores it securely and never displays it again.
   3. A name for your agent — Give your agent a name (like “Atlas” or “Helper”), or press Enter to accept the default.

   When the wizard finishes, it creates two files in your home directory:

   • ~/.comis/config.yaml — Your agent’s configuration (name, provider, settings)
   • ~/.comis/.env — Your API key, stored separately for security

   Picking an OpenAI provider: openai vs openai-codex

   On the first wizard question, two OpenAI options appear:

   Provider id	Label	Cost model	When to pick
   openai	OpenAI (GPT) — “GPT-4o, o1, o3 — API key (pay per token)“	Pay per request	You have an OpenAI API key from platform.openai.com and want GPT-4o / o1 / o3.
   openai-codex	OpenAI Codex — “ChatGPT/Codex subscription — OAuth login”	Flat ChatGPT subscription	You already pay for ChatGPT Plus / Team / Enterprise and want Codex (gpt-5.1 family). No API key needed; the wizard runs an OAuth login.

   If you pick openai, the wizard prompts for an API key as usual.

   If you pick openai-codex, the wizard prints:

   OpenAI Codex uses your ChatGPT/Codex subscription — no API key needed. Choose how you want to sign in.

   …followed by a four-option login picker:

   Option	Picker label	Use when
   Browser (auto-open)	Browser (auto-open) — “Local desktop, opens default browser”	You’re on a desktop or laptop with a graphical browser; the wizard opens a tab and waits for the OAuth callback on 127.0.0.1:1455.
   Browser (manual paste)	Browser (manual paste) — “VPS, you paste callback URL after sign-in”	The host has a browser elsewhere (e.g., your laptop), but the daemon runs on a VPS without a default browser. The wizard prints the auth URL; you paste the callback URL back after sign-in.
   Device code (phone)	Device code (phone) — “SSH/headless, type a short code on a phone”	SSH session, no clipboard, no scrollback. The wizard prints a short code and a verification URL; you open the URL on your phone and type the code.
   Skip for now	Skip for now — “finish wizard, run comis auth login later”	You want to finish the rest of the wizard now and add the OAuth profile in a later step (see below).

   The wizard auto-defaults to Device code (phone) on remote/headless hosts (when SSH_CLIENT, SSH_TTY is set or DISPLAY is unset) and to Browser (auto-open) on local desktops. You can always pick a different option from the menu.

   What Skip for now does: the wizard finishes without writing an OAuth profile. The agent config marks openai-codex as not-yet-validated. Before starting the daemon, run:

   comis auth login --provider openai-codex
   

   The CLI runs the same login flow (browser auto, browser manual, or device-code via --method device-code) and writes the resulting profile into the OAuth credential store. See comis auth login reference for all flags.

   VPS / SSH hint: For headless deployments (Hostinger, DigitalOcean, Hetzner, Render, etc.), pick Device code (phone). The browser-based options assume a graphical environment that VPS hosts typically lack. Full VPS walkthrough: Install on a VPS.

   For the full picture — PKCE flow shape, multi-account profiles, the wizard-vs-CLI parity matrix, and the threat model — see OAuth concepts.

   Non-interactive alternative

   If you prefer to skip the wizard (for example, in a CI pipeline or Docker container), you can pass everything on the command line:

   comis init --non-interactive --accept-risk --provider anthropic --api-key sk-ant-your-key-here
   

   This creates the same configuration files without prompting for input.

3. Start the daemon

   Start the Comis daemon — the background process that keeps your agents running:

   comis daemon start
   

   You should see output similar to:

   Comis daemon started
     Agent:    Atlas
     Provider: anthropic (claude-sonnet-4-5-20250929)
     Gateway:  http://localhost:4766
     Status:   ready
   

   The daemon is now running. It manages your agents, handles incoming messages, and serves the web dashboard.

   The daemon runs in the background. You can close this terminal window and it will keep running. To stop it later, run comis daemon stop.

4. Talk to your agent

   When the daemon starts, it also launches a built-in web dashboard. Open your browser and go to:

   http://localhost:4766
   

   The web dashboard provides a chat interface where you can talk directly to your agent. Type a message and press Enter:

   You:   Hello! What can you do?
   Agent: Hi! I'm Atlas, your AI assistant. I can help you with
          questions, research, writing, scheduling, and more.
          What would you like to work on?
   

   The dashboard also shows your agent’s status, memory, and configuration. You can monitor everything from this single page.

   The web dashboard is the recommended way to interact with your agent when getting started. For programmatic access, Comis also provides a JSON-RPC gateway and an OpenAI-compatible API at the same address.

5. Connect a messaging channel (optional)

   Your agent is running and you can chat through the web dashboard. But the real power of Comis is putting your agent inside the messaging apps your community already uses.

   To add a messaging channel like Discord, Telegram, or Slack, re-run the setup wizard:

   comis init
   

   The wizard detects your existing configuration and offers to add channels. Each channel has its own setup — typically you will need a bot token from the platform.

   See the Channels section for step-by-step guides for each platform.

Docker (no Node.js required)

Run Comis as a container. Best if you would rather not install Node.js or you are deploying to a server.

1. Start the container

   Pull and run the slim image. This starts the daemon, exposes the web dashboard on port 4766, and stores configuration and data in a named Docker volume so they survive restarts:

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

   The --restart unless-stopped flag is required — the wizard and any agent-initiated config change (gateway.restart, gateway.env_set, gateway.patch) signal the daemon to reload, and Docker’s restart policy is what brings the container back with the new config.

   Once running, verify the daemon is up:

   curl http://localhost:4766/health
   

   You should see:

   {"status":"ok"}
   
2. Run the setup wizard

   Configure your provider and channels by running the wizard inside the container:

   docker exec -it comis comis init
   

   The wizard walks you through selecting a provider, adding channel tokens (Telegram, Discord, Slack, etc.), and connecting your first agent. The same three questions apply: which provider, your API key, and a name for your agent.

   Configuration is written to /home/comis/.comis/config.yaml and /home/comis/.comis/.env inside the container, which map to the comis-data Docker volume. Your keys survive docker rm and docker pull as long as the volume sticks around.

3. Talk to your agent

   After the wizard finishes, the daemon picks up the new configuration automatically. Open the web dashboard in your browser:

   http://localhost:4766
   

   Type a message in the chat panel and press Enter to chat with your agent.

   Stream the daemon’s logs with docker logs -f comis. Stop the daemon with docker stop comis and start it again with docker start comis — your data and configuration persist in the comis-data volume.

For production Docker deployments — pinned version tags, custom networks, docker-compose, the separate comisai/comis-web image — see the full Docker installation guide and the Docker Hub reference.

What just happened?

Here is what happened behind the scenes when you sent that first message:

1. You typed a message in the web dashboard and pressed Enter.
2. The Comis gateway received your message and looked at the routing rules to figure out which agent should handle it.
3. Your agent received the message, checked its memory for any relevant context from past conversations, and built a prompt combining your message with its instructions.
4. The prompt was sent to your AI provider (Anthropic, OpenAI, or Google), which generated a response.
5. The agent sent the reply back through the gateway to your browser, where it appeared in the chat.

All of this happened in a few seconds. As you keep chatting, your agent builds up memory and gets better at helping you over time.

Useful commands

Now that your agent is running, here are a few commands you will use regularly:

Command	What it does
comis daemon start	Start the daemon (agents, gateway, dashboard)
comis daemon stop	Stop the daemon and all agents
comis daemon status	Check if the daemon is running
comis daemon logs	View the daemon’s log output
comis init	Re-run the setup wizard to add channels or change settings

After editing ~/.comis/config.yaml by hand, stop and restart the daemon to pick up the changes: comis daemon stop followed by comis daemon start.

Next steps

Connect a Channel

Add Discord, Telegram, Slack, WhatsApp, or any of the 9 supported platforms.

How It Works

Understand how Comis processes messages and connects your agents.

Use Cases

See real-world scenarios and what you can build with Comis.

Installation Details

Docker setup, Linux packages, requirements, and advanced configuration.