Install on Linux

Step-by-step installation guide for Ubuntu, Fedora, and Arch Linux

This guide walks you through installing Comis on a Linux server or workstation. Every command is copy-paste ready, and each step shows the expected output so you know things are working.

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

Make sure you have Node.js 22+, build tools, and an AI provider API key ready before starting. See the Requirements page for the full list.

Installation

1. Install Node.js 22

   Ubuntu / Debian

   curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
   sudo apt-get install -y nodejs
   

   Fedora / RHEL

   curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo -E bash -
   sudo dnf install -y nodejs
   

   Arch

   sudo pacman -S nodejs npm
   

   Verify the installation:

   node --version
   

   Expected output:

   v22.x.x
   
2. Install build tools

   These tools compile native modules during the Comis installation.

   Ubuntu / Debian

   sudo apt-get install -y build-essential python3
   

   Fedora / RHEL

   sudo dnf install -y gcc-c++ make python3
   

   Arch

   sudo pacman -S --needed base-devel python
   
3. Install Comis

   npm install -g comisai
   

   Verify:

   comis --version
   

   Expected output (version number — yours may differ):

   1.0.42
   

   If you get an EACCES permission error, see the “Permission denied during npm install” section in Common Issues below.

4. Run the setup wizard

   comis init
   

   The wizard walks you through three questions:

   1. Which AI provider? — Choose from Anthropic (Claude), OpenAI (GPT), Google (Gemini), and 8 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 in ~/.comis/.env 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:

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

   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 runs in the background. It manages your agents, handles incoming messages, and serves the web dashboard.

   You can close this terminal and the daemon will keep running. To stop it later, run comis daemon stop.

6. Open the 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. It also shows your agent’s status, memory usage, and configuration. Type a message and press Enter to start a conversation.

Browser tool provisioning (optional)

Three flags ship the agent browser tool inline with the install. Off by default; mix and match as your use case demands.

Flag	Adds	Use when
--with-browser	Google Chrome + headless shared libs + a widened systemd sandbox so the daemon can launch a browser. Handles Ubuntu 24.04’s t64-renamed libs and falls back to Google’s official apt repo when the chromium deb isn’t available.	You want the browser tool to work on a fresh host without manually apt installing dependencies.
--with-xvfb	Implies --with-browser. Adds Xvfb and a comis-xvfb.service companion unit that runs a virtual display on :99; the main unit’s JoinsNamespaceOf=comis-xvfb.service lets the daemon reach the X11 socket despite PrivateTmp=yes. Seeds headless: false in config.yaml.	Hitting sites that detect headless mode itself (BrowserScan, Cloudflare managed, DataDome).
--with-cloakbrowser	Implies --with-browser. Installs CloakBrowser (stealth Chromium with source-level fingerprint patches) instead of stock Chrome; the daemon auto-detects and uses the cloak binary via findChrome(). Tighter sandbox than the Chrome variant.	Bypassing Cloudflare Turnstile, FingerprintJS, BrowserScan, and Reddit’s secondary fingerprint check. See agent-tools/browser for verified outcomes.

# Bare baseline (no browser)
curl -fsSL https://comis.ai/install.sh | bash

# Stock Chrome — needed for any agent that uses the browser tool
curl -fsSL https://comis.ai/install.sh | bash -s -- --with-browser

# Cloakbrowser (stealth Chromium) — recommended for fingerprint-tier sites
curl -fsSL https://comis.ai/install.sh | bash -s -- --with-cloakbrowser

# Full stack: stealth + headed via Xvfb (for the hardest anti-bot sites)
curl -fsSL https://comis.ai/install.sh | bash -s -- --with-cloakbrowser --with-xvfb

Datacenter IPs (AWS, DigitalOcean, Hetzner, Hostinger, …) are pre-blocked by Reddit, X/Twitter, LinkedIn, and many anti-bot services at the network layer — regardless of browser fingerprint. CloakBrowser does not include a proxy. If your daemon runs on a datacenter VPS, pair the stealth flag with a residential proxy. Self-hosted on a home/office network: stealth alone usually works.

CloakBrowser’s compiled binary is under a separate license — free for self-hosted use; bundling into a service distributed to third-party customers requires an OEM license from CloakHQ. See the binary license.

The corresponding environment variables (COMIS_WITH_BROWSER, COMIS_WITH_XVFB, COMIS_WITH_CLOAKBROWSER) work too, useful in CI / non-interactive flows. The installer pre-creates browser profile dirs, seeds a browser: block in config.yaml, and (for --with-xvfb) enables + starts the companion unit before the main daemon — no manual systemd surgery needed.

Non-Interactive Install

For CI pipelines, scripting, or Docker containers, you can skip the interactive wizard entirely:

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

This creates the same ~/.comis/config.yaml and ~/.comis/.env files without prompting for input. Replace anthropic with your provider of choice and set the ANTHROPIC_API_KEY environment variable (or substitute the appropriate variable for your provider) before running.

The --accept-risk flag acknowledges that you are providing an API key on the command line rather than through the interactive prompt. See comis init --help for all 27 available flags.

OpenAI Codex on a headless server? If you are setting up on an SSH-only Linux server and pick openai-codex as your provider, the wizard auto-selects Device code login (no browser needed). You can also run it manually at any time:

comis auth login --provider openai-codex --method device-code

The CLI prints a short code and the URL https://auth.openai.com/codex/device. Open that URL on a phone or laptop browser, sign into ChatGPT, and enter the code. The CLI polls every 5 seconds and completes when the code is accepted (15-minute timeout). For the full walkthrough including multi-account profiles, see Install on a VPS.

Common Issues

Permission denied during npm install

Symptom: EACCES: permission denied when running npm install -g comisai

Fix: Configure npm to use a directory you own instead of the system-level global directory:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Then retry the install:

npm install -g comisai

node-gyp build errors

Symptom: Errors mentioning node-gyp, gyp ERR!, or make: g++: not found during installation.

Cause: Missing build tools required for compiling native modules.

Fix: Install the build tools for your distribution (Step 2 above), then retry:

npm install -g comisai

If the problem persists, check that Python 3 is installed and accessible as python3. See the Requirements page for the full list of build dependencies.

Port 4766 already in use

Symptom: The daemon starts but reports that port 4766 is already in use.

Diagnose: Find what is using the port:

lsof -i :4766

Fix: Either stop the other process, or change the Comis gateway port in ~/.comis/config.yaml:

gateway:
  port: 4800

Then restart the daemon:

comis daemon stop
comis daemon start

Daemon starts but no web dashboard

Symptom: comis daemon start succeeds but http://localhost:4766 does not load in your browser.

Diagnose: Run the built-in diagnostic tool:

comis doctor

This checks five categories: config, daemon, gateway, channels, and workspace. Look for failures in the “gateway” category.

Common causes:

• The gateway is disabled in your config. Make sure gateway.enabled is not set to false.
• The gateway is bound to a different host. Check the gateway.host setting in your config file.
• A firewall is blocking the port.

Next Steps

Configuration Guide

Customize your agent’s settings, add channels, and fine-tune behavior.

Verification

Run diagnostic checks to confirm everything is working.

Connect a Channel

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