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.

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

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

1. Connect to the host

   ssh root@your-server-ip
   

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

2. Download and review the installer

   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.

3. Run the reviewed installer

   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.

4. Initialize as the service user

   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.

5. Verify the service

   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.

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:

# 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 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:

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:

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:

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 for the storage and trust boundaries.

Operate the service

The CLI detects the installer-managed supervisor:

comis daemon status
comis daemon restart
comis daemon logs --follow

As an administrator, the equivalent system commands are:

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:

sudo systemctl cat comis.service

See systemd operations 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:

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

The installer reports incomplete service setup

Do not continue from the success path. Inspect:

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.

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.

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; do not assume commands are isolated merely because the daemon itself runs under systemd.

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.

Uninstall

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

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.

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

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

Connect channels

Add only the messaging adapters your deployment needs.

Configure agents

Set models, tools, budgets, memory, and routing.

Production hardening

Review host, gateway, tool, credential, and approval boundaries.

Operations

Monitor health, logs, metrics, and background work.