> ## Documentation Index
> Fetch the complete documentation index at: https://comis-feature-matrix-channel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://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](https://www.docker.com/get-started/). Pick this if
you would rather not install Node.js or you are running on a server.
## Install and run
Run Comis directly on your machine. Best if you already have Node.js or
plan to develop against the source.
Open your terminal and install Comis globally with npm:
```bash theme={}
npm install -g comisai
```
Once the installation finishes, verify it worked:
```bash theme={}
comis --version
```
You should see the installed version, for example:
```
1.0.53
```
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](/installation/index) for alternatives.
Run the interactive setup wizard:
```bash theme={}
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:
```bash theme={}
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](/reference/cli#comis-auth) 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](/installation/install-vps).
For the full picture -- PKCE flow shape, multi-account profiles, the wizard-vs-CLI parity matrix, and the threat model -- see [OAuth concepts](/security/oauth).
If you prefer to skip the wizard (for example, in a CI pipeline or Docker
container), you can pass everything on the command line:
```bash theme={}
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.
Start the Comis daemon -- the background process that keeps your agents running:
```bash theme={}
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`.
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.
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:
```bash theme={}
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](/channels/index) section for step-by-step guides for each
platform.
Run Comis as a container. Best if you would rather not install Node.js or
you are deploying to a server.
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:
```bash theme={}
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:
```bash theme={}
curl http://localhost:4766/health
```
You should see:
```json theme={}
{"status":"ok"}
```
Configure your provider and channels by running the wizard inside the
container:
```bash theme={}
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.
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](/installation/install-docker) and the
[Docker Hub reference](/operations/docker-hub).
## 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
Add Discord, Telegram, Slack, WhatsApp, or any of the 11 supported platforms.
Understand how Comis processes messages and connects your agents.
See real-world scenarios and what you can build with Comis.
Docker setup, Linux packages, requirements, and advanced configuration.