Install with npm on Linux

Install Comis as your current user without changing system services

This path installs the Comis CLI and runtime for your current user. It does not create a service account, register systemd units, or install host tools such as Bubblewrap, ffmpeg, Chrome, or Xvfb.

Use the VPS installer when you want Comis to manage those host dependencies and run as a dedicated Linux service.

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

Prerequisites

Install:

• Node.js 22.19.0 or newer;
• npm;
• Python 3; and
• the compiler toolchain used by native Node modules.

Use your distribution’s package manager or the official Node.js download instructions. Common build-tool packages are:

Ubuntu / Debian

sudo apt-get update
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 nodejs npm

Verify the runtime before installing Comis:

node --version
npm --version

The Node.js version must be at least v22.19.0.

Install and initialize

1. Install Comis

   npm install --global comisai
   comis --version
   

   If the global install reports EACCES, configure a user-owned npm prefix as shown under Permission denied during npm install.

2. Run setup

   comis init
   

   The wizard reviews storage, model authentication, agents, optional channels, gateway access, workspace, tools, media, and recall before writing files.

   Encrypted storage is the default. Back up ~/.comis/.env; it contains the master key required to recover credentials stored in ~/.comis/secrets.db.

3. Start and verify the daemon

   comis daemon start
   comis status
   comis health
   

   comis daemon start launches a detached user process. It is not registered as an operating-system service and does not automatically start after reboot.

4. Open the dashboard

   Open http://127.0.0.1:4766 on the same host. Keep the gateway bound to loopback unless you have configured authentication, TLS, and network access controls for a remote deployment.

Browser tool provisioning

The npm package includes the browser-tool code, but this installation path does not install a browser binary or virtual display. Install a supported Chrome or Chromium runtime yourself, or use the reviewed managed-host installer, which provisions Chrome and Xvfb on Linux on a best-effort basis.

See Browser tool for runtime detection, configuration, isolation requirements, and optional browser variants. A configured browser tool reports an actionable unavailable result when no compatible runtime can launch.

Non-interactive setup

For controlled automation, the setup command can run without prompts:

export ANTHROPIC_API_KEY="<set-in-your-secret-runner>"
comis init --non-interactive --accept-risk \
  --provider anthropic \
  --api-key "$ANTHROPIC_API_KEY" \
  --agent-name "Atlas"

--accept-risk acknowledges that command arguments may be visible through process inspection, shell history, or CI logs. Prefer interactive setup or a secret-aware runner, and never save a literal credential in a script.

For OpenAI Codex on a headless host, use device-code login instead of a static key:

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

Common issues

Permission denied during npm install

Configure npm to install global packages in your home directory:

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

Native module build fails

Confirm Python 3 and your distribution’s compiler toolchain are installed, then retry npm install --global comisai. See Requirements for the supported runtime floor.

Port 4766 is already in use

Identify the listener with lsof -i :4766, or choose a different gateway.port in ~/.comis/config.yaml, then restart the daemon.

The dashboard does not open

Run comis doctor and inspect the gateway findings. Confirm the daemon is running, gateway.enabled is true, and the configured host and port match the URL you opened.

Next steps

Configuration

Configure models, agents, credentials, tools, and channels.

Verification

Validate the daemon and its configured integrations.

Production hardening

Restrict tools and secure gateway and host boundaries.

VPS installation

Use a dedicated service account and managed systemd unit.