> ## 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 on a Linux server

> Run Comis under a managed systemd service on a Linux host

The managed-host installer can install supported host dependencies, create a
dedicated `comis` account, install the package, and register a hardened systemd
service. Use this path on a Linux server where you control the operating system.

For a user-scoped install that does not change system services, use the [npm
guide](/installation/install-linux).

<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" />

## Before you begin

You need:

* a Linux host with a working systemd installation;
* root access or a user that can run `sudo`;
* outbound HTTPS for system and npm packages;
* one usable model path: a provider credential, supported OAuth login, or a
  local provider; and
* enough memory and disk for your chosen channels, tools, browser runtime, and
  local models.

Channels are optional. Keep the gateway on loopback unless you have configured
authentication, TLS, and network controls for remote access.

## Install Comis

<Steps>
  <Step title="Connect to the host">
    ```bash theme={}
    ssh root@your-server-ip
    ```

    Use the account and SSH-key policy defined by your hosting provider or
    organization.
  </Step>

  <Step title="Download and review the installer">
    ```bash theme={}
    curl -fsSL --proto '=https' --tlsv1.2 https://comis.ai/install.sh -o comis-install.sh
    less comis-install.sh
    bash comis-install.sh --dry-run
    ```

    The dry run prints the intended package, account, file, and service changes
    without applying them. Review `bash comis-install.sh --help` for service,
    browser, and non-interactive options.
  </Step>

  <Step title="Run the reviewed installer">
    ```bash theme={}
    bash comis-install.sh
    ```

    On a root-run Linux systemd host, the default layout installs Comis for a
    dedicated `comis` user and writes an installer-managed
    `/etc/systemd/system/comis.service`. A regular-user run offers to elevate;
    `--no-user` is the explicit current-user alternative.

    The installer must finish with a verified CLI and successful service setup.
    Treat any warning or nonzero exit as incomplete installation and inspect the
    command output before continuing.
  </Step>

  <Step title="Initialize as the service user">
    ```bash theme={}
    su - comis
    comis init
    ```

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

    Encrypted credential storage is the default. Back up
    `/home/comis/.comis/.env`; its master key is required to recover
    `/home/comis/.comis/secrets.db`.
  </Step>

  <Step title="Verify the service">
    ```bash theme={}
    comis status
    comis health
    comis doctor
    ```

    Do not infer readiness from a running process alone. Resolve reported model,
    channel, gateway, storage, or sandbox findings before exposing the service.
  </Step>
</Steps>

## Browser choices

On Linux, the managed installer attempts to provision Chrome and Xvfb by
default. Provisioning is best-effort: failure to install a browser does not
pretend the browser tool is usable, and a user-scoped systemd install runs the
browser headless because it cannot manage the system Xvfb companion.

Run the reviewed local installer with the option you need:

```bash theme={}
# Minimal host footprint: no browser runtime
bash comis-install.sh --without-browser

# Chrome without the Xvfb companion
bash comis-install.sh --without-xvfb

# Optional alternative Chromium runtime
bash comis-install.sh --with-cloakbrowser
```

CloakBrowser does not provide a proxy or guarantee access to any site. Review
its separate binary license and the target site's terms before using it. See
[Browser tool](/agent-tools/browser) for configuration and isolation details.

## Optional egress diagnostics

The installer does not change iptables by default. On a Linux systemd install
that creates the dedicated `comis` user, you can explicitly enable outbound
packet logging after reviewing it:

```bash theme={}
COMIS_ENABLE_EGRESS_LOGGING=1 bash comis-install.sh --dry-run
COMIS_ENABLE_EGRESS_LOGGING=1 bash comis-install.sh
```

This creates a uid-scoped `COMIS_EGRESS` iptables chain with `LOG+ACCEPT`
rules. It records outbound packet metadata, including remote destinations, in
the kernel journal under the `comis-egress:` prefix. Logging is limited to 10
entries per minute with a burst of 20. It does not inspect packet content and
does not block or restrict traffic. Destination metadata can be sensitive, so
egress logging is disabled by default.

Review captured entries with:

```bash theme={}
journalctl -k | grep 'comis-egress:'
```

`--uninstall --purge` removes an installer-created `COMIS_EGRESS` chain even
when the opt-in flag is not present on the uninstall command.

## Codex OAuth on headless hosts

For OpenAI Codex, use device-code login from the service user's TTY:

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

Open the displayed URL on another device, enter the short code, and return to
the terminal when authorization completes. Tokens are stored according to the
configured credential-storage mode. See [OAuth security](/security/oauth) for
the storage and trust boundaries.

## Operate the service

The CLI detects the installer-managed supervisor:

```bash theme={}
comis daemon status
comis daemon restart
comis daemon logs --follow
```

As an administrator, the equivalent system commands are:

```bash theme={}
sudo systemctl status comis.service
sudo systemctl restart comis.service
journalctl -u comis.service -f
```

The installer-generated unit is the source of truth for the supported Node.js
permission flags, filesystem access, Bubblewrap namespaces, browser paths, and
restart behavior. Inspect the deployed unit with:

```bash theme={}
sudo systemctl cat comis.service
```

See [systemd operations](/operations/systemd) before adding a drop-in or taking
ownership of the unit.

## Upgrade

Download the current installer to a new file, inspect it again, and preview the
upgrade before running it:

```bash theme={}
curl -fsSL --proto '=https' --tlsv1.2 https://comis.ai/install.sh -o comis-install.next.sh
less comis-install.next.sh
bash comis-install.next.sh --dry-run
bash comis-install.next.sh
```

The installer preserves Comis data and refuses to overwrite a service unit that
no longer carries its valid managed checksum. Back up the data directory and
master key before upgrading.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The installer reports incomplete service setup">
    Do not continue from the success path. Inspect:

    ```bash theme={}
    sudo systemctl status comis.service --no-pager
    journalctl -u comis.service -n 100 --no-pager
    ```

    Correct the reported package, permission, configuration, or port problem,
    then rerun the same reviewed installer.
  </Accordion>

  <Accordion title="The daemon starts but health checks fail">
    Run `comis doctor` as the service user and inspect recent logs. Confirm the
    selected model has working authentication and the gateway host and port are
    not already in use.
  </Accordion>

  <Accordion title="The exec sandbox is unavailable">
    Linux tool isolation requires Bubblewrap plus host support for unprivileged
    user namespaces. Check the daemon's sandbox-detection log and follow
    [Production hardening](/security/hardening); do not assume commands are
    isolated merely because the daemon itself runs under systemd.
  </Accordion>

  <Accordion title="The browser tool is unavailable">
    Run `comis doctor`, inspect browser-related logs, and verify a supported
    browser binary can launch as the service user. Re-run the installer only
    after reviewing the requested browser option and its dry-run output.
  </Accordion>
</AccordionGroup>

## Uninstall

The default uninstall removes the managed service and CLI but preserves data:

```bash theme={}
bash comis-install.sh --uninstall
```

For the default dedicated-user install, the preserved directory is
`/home/comis/.comis` (or the selected user's home). The installer prints the
resolved path in the confirmation and completion messages.

<Warning>
  `--remove-user` implies `--purge`: it deletes the dedicated account and Comis
  data, the systemd units, Xvfb runtime files, the Comis sudoers rule, the
  installer-managed AppArmor profile, and the installer's ownership receipt. The
  account is removed only when that receipt, its root-owned identity marker, and
  the receipt-bound account identity prove the installer created the same
  account. The receipt records removal as a one-way state transition so a retry
  never deletes a recreated user or group. Back up the data directory and
  encryption key, then inspect the displayed uninstall plan before confirming.
</Warning>

```bash theme={}
sudo bash comis-install.sh --uninstall --remove-user --yes
```

Shared host dependencies are preserved because other software may use them.
This includes Node.js, uv, Rust, browser/Xvfb packages, build tools, and package
repositories. Run with `--dry-run` first to preview every Comis-specific path.

## Next steps

<CardGroup cols={2}>
  <Card title="Connect channels" icon="comments" href="/channels/index">
    Add only the messaging adapters your deployment needs.
  </Card>

  <Card title="Configure agents" icon="robot" href="/agents/index">
    Set models, tools, budgets, memory, and routing.
  </Card>

  <Card title="Production hardening" icon="shield" href="/security/hardening">
    Review host, gateway, tool, credential, and approval boundaries.
  </Card>

  <Card title="Operations" icon="chart-line" href="/operations/index">
    Monitor health, logs, metrics, and background work.
  </Card>
</CardGroup>