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

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

<Warning>
  systemd is Linux-only. Use [pm2](/operations/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.
</Warning>

## Install safely

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

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

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

## Manage the service

For a system service:

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

For a user service:

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

```bash theme={}
sudo loginctl enable-linger "$(id -un)"
```

Check application readiness independently of systemd's process state:

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

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

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

```bash theme={}
sudo systemctl reset-failed comis.service
sudo systemctl start comis.service
```

See [Logging](/operations/logging) for structured logs and
[Troubleshooting](/operations/troubleshooting) for daemon and gateway checks.

## Related pages

<CardGroup cols={2}>
  <Card title="Linux installation" icon="linux" href="/installation/install-linux">
    Install Comis and review Linux-specific dependencies.
  </Card>

  <Card title="Daemon" icon="server" href="/operations/daemon">
    Understand startup, health, and shutdown behavior.
  </Card>

  <Card title="Node permissions" icon="shield" href="/reference/node-permissions">
    Review the runtime permission boundary and compatibility tradeoffs.
  </Card>

  <Card title="Docker" icon="docker" href="/operations/docker">
    Run Comis without a host systemd unit.
  </Card>
</CardGroup>