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. When you need to update the worker or change its configuration, gentic restart applies the change without touching your service unit file.
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 | Backend | Service file location |
|---|
| Linux (user scope) | systemd user unit | ~/.config/systemd/user/gentic.service |
| Linux (system scope) | systemd system unit | /etc/systemd/system/gentic.service |
| macOS | launchd agent | ~/Library/LaunchAgents/dev.gentic.agent.plist |
| Other | Detached process + pidfile | N/A |
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 worker 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 worker:
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
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):
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):
Run in the foreground
Run the worker 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 four fields.
| Field | Description |
|---|
| Auth | Whether credentials are configured, with the API key masked (first 3 and last 4 characters shown) and the API URL displayed in full. |
| Service | The service state (running, stopped, or not-installed), the backend name (e.g. systemd, launchd, or fallback), the process PID if running, and the uptime since the process started. |
| Boot | Whether the service is registered to start automatically on boot or login (enabled or disabled). |
| Last run | The timestamp of the most recently completed issue run. |
--json flag returns the same information as a JSON object with the following keys: auth, apiUrl, maskedApiKey, service, serviceBackend, pid, uptimeSeconds, bootEnabled, and lastRun.
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 worker 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.
Typical production setup
The following example builds the standalone binary, copies it to a production server, authenticates, and starts the managed service.
# On your build machine
cd apps/gentic
./scripts/build-binary.sh bun-linux-x64 dist/linux-x64
scp -r dist/linux-x64 deploy@prod-server:/opt/gentic
# On the production server
cd /opt/gentic
./gentic auth login --api-url https://gentic.chat/api/v1 --api-key <your-key>
./gentic start
# Verify it is running
./gentic status
