> ## Documentation Index > Fetch the complete documentation index at: https://comis-feature-skill-archive-import.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](/installation/requirements) page for the full list. ## Installation ```bash theme={} curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs ``` ```bash theme={} curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo -E bash - sudo dnf install -y nodejs ``` ```bash theme={} sudo pacman -S nodejs npm ``` Verify the installation: ```bash theme={} node --version ``` Expected output: ``` v22.x.x ``` These tools compile native modules during the Comis installation. ```bash theme={} sudo apt-get install -y build-essential python3 ``` ```bash theme={} sudo dnf install -y gcc-c++ make python3 ``` ```bash theme={} sudo pacman -S --needed base-devel python ``` ```bash theme={} npm install -g comisai ``` Verify: ```bash theme={} 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. ```bash theme={} 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 ```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 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`. 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](/agent-tools/browser#stealth-mode-anti-bot-detection) for verified outcomes. | ```bash theme={} # 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](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md). 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: ```bash theme={} 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: ```bash theme={} 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](/installation/install-vps#codex-oauth-on-headless-hosts). ## Common Issues **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: ```bash theme={} mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc ``` Then retry the install: ```bash theme={} npm install -g comisai ``` **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: ```bash theme={} npm install -g comisai ``` If the problem persists, check that Python 3 is installed and accessible as `python3`. See the [Requirements](/installation/requirements) page for the full list of build dependencies. **Symptom:** The daemon starts but reports that port 4766 is already in use. **Diagnose:** Find what is using the port: ```bash theme={} lsof -i :4766 ``` **Fix:** Either stop the other process, or change the Comis gateway port in `~/.comis/config.yaml`: ```yaml theme={} gateway: port: 4800 ``` Then restart the daemon: ```bash theme={} comis daemon stop comis daemon start ``` **Symptom:** `comis daemon start` succeeds but `http://localhost:4766` does not load in your browser. **Diagnose:** Run the built-in diagnostic tool: ```bash theme={} 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 Customize your agent's settings, add channels, and fine-tune behavior. Run diagnostic checks to confirm everything is working. Add Discord, Telegram, Slack, or any of the 10 supported platforms.