> ## Documentation Index
> Fetch the complete documentation index at: https://comis-fix-skill-import-vetting-gate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/installation/install-vps) when you want Comis to manage
those host dependencies and run as a dedicated Linux service.

<Info>
  You don't need to understand the technical details to use this feature. The configuration examples below are copy-paste ready.
</Info>

<Snippet file="invocation-modes.mdx" />

## 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](https://nodejs.org/en/download). Common build-tool packages are:

<Tabs>
  <Tab title="Ubuntu / Debian">
    ```bash theme={}
    sudo apt-get update
    sudo apt-get install -y build-essential python3
    ```
  </Tab>

  <Tab title="Fedora / RHEL">
    ```bash theme={}
    sudo dnf install -y gcc-c++ make python3
    ```
  </Tab>

  <Tab title="Arch">
    ```bash theme={}
    sudo pacman -S --needed base-devel python nodejs npm
    ```
  </Tab>
</Tabs>

Verify the runtime before installing Comis:

```bash theme={}
node --version
npm --version
```

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

## Install and initialize

<Steps>
  <Step title="Install Comis">
    ```bash theme={}
    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](#permission-denied-during-npm-install).
  </Step>

  <Step title="Run setup">
    ```bash theme={}
    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`.
  </Step>

  <Step title="Start and verify the daemon">
    ```bash theme={}
    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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](/installation/install-vps), which provisions Chrome and Xvfb on Linux
on a best-effort basis.

See [Browser tool](/agent-tools/browser) 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:

```bash theme={}
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:

```bash theme={}
comis auth login --provider openai-codex --method device-code
```

## Common issues

<AccordionGroup>
  <Accordion title="Permission denied during npm install">
    Configure npm to install global packages in your home directory:

    ```bash theme={}
    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
    ```
  </Accordion>

  <Accordion title="Native module build fails">
    Confirm Python 3 and your distribution's compiler toolchain are installed,
    then retry `npm install --global comisai`. See
    [Requirements](/installation/requirements) for the supported runtime floor.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="sliders" href="/installation/configuration">
    Configure models, agents, credentials, tools, and channels.
  </Card>

  <Card title="Verification" icon="circle-check" href="/installation/verify">
    Validate the daemon and its configured integrations.
  </Card>

  <Card title="Production hardening" icon="shield" href="/security/hardening">
    Restrict tools and secure gateway and host boundaries.
  </Card>

  <Card title="VPS installation" icon="server" href="/installation/install-vps">
    Use a dedicated service account and managed systemd unit.
  </Card>
</CardGroup>