CCortex

DOCS ยท DEPLOYMENT

Run Cortex as a user service

Install Cortex as a systemd user service when it should keep running after the terminal closes. The service uses your OS account and does not require sudo.

Commands

cortex service install
# Optional install flags:
#   --host HOST
#   --port PORT
#   --root DIRECTORY
#   --data DIRECTORY
#   --public-origin URL
#   --trust-proxy

# Example: listen on 127.0.0.1:7401
cortex service install --port 7401
cortex service start
cortex service stop
cortex service restart
cortex service status
cortex service logs
cortex service logs --follow
cortex service uninstall

The installed unit records its listener and paths explicitly. Defaults come from CORTEX_HOST/CORTEX_PORT, then fall back to 127.0.0.1:7331. The legacy --listen form remains supported.

The unit lives at ~/.config/systemd/user/cortex.service. Cortex manages it through systemctl --user and reads logs through journalctl --user-unit cortex.service.

Install behavior

service install writes the unit atomically and records an integrity header. It refuses unstable executable paths and will not overwrite a foreign or hand-edited unit.

  • Safe reinstall: unchanged active installations are left alone; configuration changes reload and restart the service.
  • Transactional failure: the previous unit, enablement and running state are restored. This includes enabled-runtime: runtime-only enablement is restored without leaving a persistent link.
  • State protection: masked, failed, generated and other states that cannot be restored exactly are rejected before changes begin; unmask or stop the service first.
  • Data preservation: uninstall preserves configuration, conversations and data.

status reports enablement, running state, PID, version, listener and the public GET /api/health check. It exits nonzero when the service is missing or failed. The unit stores the executable's absolute path, so reinstall after moving the binary.

GitHub CLI authentication

The unit records HOME and, when present, the location of ~/.config/gh/hosts.yml. Cortex and its agents can then use your existing GitHub CLI login without copying credentials. If the desktop keyring is locked, run gh auth login once in your session first.

User-service limitation

cortex service manages a per-OS-user systemd service. System-wide mode (cortex service install --system) is a documented follow-up and is not yet supported. OpenCode's own configuration and session data remain isolated in per-run temporary directories.

Persistence and lingering

Closing the terminal does not stop Cortex. Use cortex service stop to stop it or cortex service uninstall to remove the unit. It normally starts when your user manager starts.

If Cortex should keep running after you log out, or start at boot before any interactive login, the user manager must be allowed to run without a session. That is what lingering enables:

loginctl show-user "$USER" -p Linger
loginctl enable-linger "$USER"

Cortex never enables lingering automatically. Enable it only when Cortex must run without an active login session.