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

   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

The agent browser tool ships enabled by default, so the installer provisions its runtime by default too: stock Chrome + headless shared libs, plus Xvfb + a headed companion unit. Provisioning is strictly best-effort — if Chromium or Xvfb can’t install on this host (arm64, locked-down apt, rootless), the install never aborts; the browser tool simply falls back to what’s available (see the fallback note below). Opt out for a minimal footprint, or add the stealth variant, with these flags:

Flag	Effect	Use when
--with-browser	On by default. 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.	Kept on unless you opt out — the browser tool needs a Chrome binary to launch.
--without-browser	Opt out of the whole browser stack (skips Chromium, headless libs, and the Xvfb unit) for a minimal footprint. The browser tool stays enabled in config but fails honestly at use for lack of a runtime. Same as COMIS_WITH_BROWSER=0.	You don’t use the browser tool and want the smallest install.
--with-xvfb	On by default (implies --with-browser). Adds Xvfb and a comis-xvfb.service companion unit that runs a virtual display on :99; both units bind a shared /run/comis-x11 dir onto /tmp/.X11-unix so the daemon reaches the X11 socket despite PrivateTmp=yes. Seeds headless: false in config.yaml only when Xvfb actually installed.	Kept on unless you opt out — needed for sites that detect headless mode itself (BrowserScan, Cloudflare managed, DataDome).
--without-xvfb	Keep the (default) headless browser but drop the heavier Xvfb headed stack + companion unit. Same as COMIS_WITH_XVFB=0.	You want the browser tool but not headed mode / the extra unit.
--with-cloakbrowser	Opt-in (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.

# Default install — browser tool + headed (Xvfb) stack provisioned best-effort
curl -fsSL https://comis.ai/install.sh | bash

# Minimal footprint — no browser runtime at all
curl -fsSL https://comis.ai/install.sh | bash -s -- --without-browser

# Headless-only — keep the browser tool, drop the heavier headed Xvfb stack
curl -fsSL https://comis.ai/install.sh | bash -s -- --without-xvfb

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

Headed provisioning degrades gracefully to headless. Chromium always installs before Xvfb, and the headed decision keys off ground truth — whether the Xvfb binary is actually present — not the flag. So if the Xvfb package or its companion unit can’t install (e.g. a rootless install can’t register a system unit), the installer downshifts to headless: it skips the companion unit and seeds headless: true, and the browser tool works on the installed Chromium. You never end up configured headed against a display that isn’t there.

Run as a regular user, these one-liners ask to re-run themselves with sudo and install under a dedicated comis system user — the secure default on Linux. Pass --no-user (or set COMIS_NO_USER=1) for a current-user install; non-interactive runs without root require one of the two choices explicitly.

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 work too, useful in CI / non-interactive flows: COMIS_WITH_BROWSER=0|1 and COMIS_WITH_XVFB=0|1 (both default 1 — set 0 for the opt-outs above), and COMIS_WITH_CLOAKBROWSER=1. The installer pre-creates browser profile dirs, seeds a browser: block in config.yaml, and (when Xvfb installed) 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 11 supported platforms.