systemd

Run and manage Comis as an installer-managed Linux service

Comis can run as a system or user systemd service on Linux. The managed-host installer is the source of truth for both unit types: it resolves the installed Node.js and daemon paths, writes the unit, and enables and starts it unless the corresponding installer opt-outs are selected.

systemd is Linux-only. Use pm2 on macOS. Comis requires Node.js 22.19.0 or newer; service-managed installs require a system-installed Node binary rather than a version-manager shim.

Install safely

Download the installer, inspect it, and preview its host changes before running it:

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
bash comis-install.sh

The default --service auto selection is:

Context	Service mode	Unit path	Runtime identity
Linux as root	systemd	/etc/systemd/system/comis.service	Dedicated comis user by default
Linux without root	systemd-user	~/.config/systemd/user/comis.service	Current user

Select a mode explicitly with --service systemd, --service systemd-user, or --service none. Run bash comis-install.sh --help for the complete set of service, browser, and autostart options.

The system service normally keeps data and configuration under /home/comis/.comis; the exact service home is resolved from the selected user. Its environment file is /etc/comis/env. The user service uses ~/.comis for data, configuration, and its environment file.

The installer can provision an Xvfb companion only for a system service. A systemd-user install explicitly uses headless browser mode and does not render a comis-xvfb.service dependency or DISPLAY=:99. For installer-managed headed mode, use a root system-service install.

Manage the service

For a system service:

sudo systemctl status comis.service --no-pager
sudo systemctl restart comis.service
sudo journalctl -u comis.service -f

For a user service:

systemctl --user status comis.service --no-pager
systemctl --user restart comis.service
journalctl --user -u comis.service -f

User services normally stop after logout. Enable lingering if this service must continue without an active login session:

sudo loginctl enable-linger "$(id -un)"

Check application readiness independently of systemd’s process state:

curl -fsS http://127.0.0.1:4766/health

Managed unit contract

The installer renders one checksum-tagged comis.service unit. It refuses to overwrite a unit whose managed body was edited by hand.

Setting	Current behavior
Type=exec	systemd considers startup successful after execve(). Comis does not emit sd_notify readiness or watchdog messages. Use /health for readiness.
ExecStart	Uses resolved absolute paths and Node’s permission model, including --allow-addons, --allow-worker, and scoped write access.
Restart policy	Restart=on-failure restarts crashes. Exit code 42 is classified as successful and explicitly forced to restart for Comis-initiated reloads.
KillMode=process	Signals only the daemon during stop so detached durable terminal sessions are not killed with the whole cgroup.
Filesystem boundary	ProtectSystem=strict and ProtectHome=read-only apply first; ReadWritePaths grants the selected service home and data directory. Agent commands receive narrower Bubblewrap mounts.
Namespace policy	The unit permits the namespace and mount operations required for Bubblewrap rather than disabling namespaces globally.
Memory execution	MemoryDenyWriteExecute and --jitless are intentionally absent because they break V8, WebAssembly, and supported native dependencies.

KillMode=process has a deliberate tradeoff: after a hard crash, another long-lived child can remain briefly until the daemon restarts. Graceful shutdown still cleans up registered children, and terminal sandbox children use their own parent-death behavior.

When system-scope Xvfb provisioning succeeds, the installer also writes /etc/systemd/system/comis-xvfb.service. The two services share only the X11 socket through /run/comis-x11; the daemon sees that socket read-only.

Configuration and overrides

Prefer rerunning the reviewed installer when the installed binary path, service identity, browser mode, or hardening contract changes. A managed unit includes a checksum; if its body has been edited, the installer leaves it untouched and reports how to regenerate it.

Use a systemd drop-in for an intentional local override instead of editing the managed unit:

sudo systemctl edit comis.service
sudo systemctl daemon-reload
sudo systemctl restart comis.service

For a user service, use the corresponding systemctl --user edit, daemon-reload, and restart commands. Review overrides carefully: changing the service type, kill mode, namespace policy, or write paths can disable restart behavior, durable terminals, or command isolation.

After changing /etc/comis/env for a system service or ~/.comis/env for a user service, restart the matching unit. Do not place credentials in config.yaml; use Comis’s secret-management flow.

Troubleshooting

Inspect the rendered unit and recent logs before changing it:

sudo systemctl cat comis.service
sudo systemctl status comis.service --no-pager --lines=30
sudo journalctl -u comis.service -n 100 --no-pager

For a user service, add --user to systemctl and journalctl as shown above. If repeated startup failures reached the unit’s start limit, fix the reported cause and clear the failed state:

sudo systemctl reset-failed comis.service
sudo systemctl start comis.service

See Logging for structured logs and Troubleshooting for daemon and gateway checks.

Related pages

Linux installation

Install Comis and review Linux-specific dependencies.

Daemon

Understand startup, health, and shutdown behavior.

Node permissions

Review the runtime permission boundary and compatibility tradeoffs.

Docker

Run Comis without a host systemd unit.