Skip to main content
The gentic CLI manages its own background service — you do not need a separate process manager like pm2 or a hand-written systemd unit file. Running gentic start installs and starts a native OS service for your platform, configures it to restart automatically on crash, and registers it to launch again on reboot. Use gentic reload after changing runtime configuration, or gentic restart after upgrading the host or changing its connection settings.
Always use gentic start in production instead of running gentic run directly in a terminal session. The managed service handles automatic restarts on crash and survives reboots; a foreground process in a terminal does not.

​
Platform behavior

The service backend is selected automatically based on the host operating system.
On platforms without a native service manager (anything other than Linux with systemd or macOS), gentic start falls back to launching a detached background process tracked by a pidfile. The host will not restart on crash and will not survive a reboot. Use a dedicated process manager on those platforms.

​
Commands

​
Start the service

Install the service unit (if it does not already exist) and start the host:
Start the service now but do not register it to launch automatically after a reboot or login:
Install and start a system-wide service unit instead of a per-user one. Requires root or sudo. Linux and systemd only:

​
Stop the service

A stop is durable: the host stays stopped across logouts and reboots until you run gentic start (or gentic restart) again. On macOS this records a launchd disable override alongside the agent’s plist; on Linux it disables the systemd unit. gentic status reports Boot: disabled while a host is stopped this way. Stop the system-wide service instead of the per-user one (Linux/systemd only):

​
Restart the service

Restart the system-wide service instead of the per-user one (Linux/systemd only):

​
Reload host configuration

Re-read runtime configuration without interrupting active issue runs:
For a system-wide host on Linux:
Host identity, credential, and API URL changes still require gentic restart.

​
Check service status

Display a human-readable summary of authentication state, service state, uptime, and boot configuration:
Output a machine-readable JSON object — useful for monitoring scripts or deployment health checks:
Check the system-wide service rather than the per-user one (Linux/systemd only):

​
View service logs

Stream the host service’s logs. On Linux with systemd this delegates to journalctl for the gentic unit; on other platforms it tails the log file that the fallback backend writes to:
Follow the log output as it is written (equivalent to tail -f or journalctl -f):
Show logs for the system-wide service instead of the per-user one (Linux/systemd only):

​
Run in the foreground

Run the host directly in the current terminal session. Use this during local development or when debugging an issue — not in production:

​
Understanding gentic status output

gentic status displays a summary panel with the following fields. If no host is connected, gentic status skips the service and host fields entirely and instead prints the connect hint, the config file path, and the tools check.

​
Why the tools check matters

Every issue run shells out to gh to interact with GitHub, and to either claude or codex depending on the issue’s agent provider. The host can claim issues for all supported providers, so gentic status checks both agent CLIs. Checking gentic status after installing the host — and any time you rotate credentials — surfaces those problems before you queue a real issue. The --json flag returns the same information as a JSON object. For a connected host the top-level keys are auth, host, hostId, apiUrl, maskedHostCredential, setupState, configFile, agents, service, serviceBackend, pid, uptimeSeconds, bootEnabled, lastRun, and tools. The tools object contains github, claude, and codex entries, and each entry has installed (boolean), authenticated (boolean), and version (string or null). Colored icons are only emitted in text output; --json is unaffected by NO_COLOR or non-TTY stdout. Two shapes differ, so scripts should branch on host before reading service fields:
  • No host connected — only host (set to "not-connected"), configFile, and tools are returned.
  • Service state unavailable — the service keys (service, serviceBackend, pid, uptimeSeconds, bootEnabled, lastRun) are replaced by a single serviceError string describing why the backend could not be queried.
pid and uptimeSeconds are omitted when the service is not running.

​
The --no-boot flag

Pass --no-boot to gentic start when you want the service to run right now but not register itself to start automatically after a system reboot. This is useful for short-lived host environments — such as CI-backed VMs or spot instances — where you control the lifecycle externally.
When --no-boot is set, gentic status reports Boot: disabled. You can re-enable boot registration at any time by running gentic start again without the flag. The preference sticks across a stop: gentic restart after a gentic stop restores whatever the last gentic start asked for, so a --no-boot host is never silently promoted to starting on boot.

​
Typical production setup

The following example builds the standalone binary, copies it to a production server, authenticates, and starts the managed service.