docs: clarify gateway service scopes (#1378)

cron/__init__.py

@@ -7,7 +7,8 @@ This module provides scheduled task execution, allowing the agent to:
 - Execute tasks in isolated sessions (no prior context)
 
 Cron jobs are executed automatically by the gateway daemon:
-    hermes gateway install    # Install as system service (recommended)
+    hermes gateway install    # Install as a user service
+    sudo hermes gateway install --system  # Linux servers: boot-time system service
     hermes gateway            # Or run in foreground
 
 The gateway ticks the scheduler every 60 seconds. A file lock prevents

hermes_cli/cron.py

@@ -96,6 +96,7 @@ def cron_list(show_all: bool = False):
     if not find_gateway_pids():
         print(color("  ⚠  Gateway is not running — jobs won't fire automatically.", Colors.YELLOW))
         print(color("     Start it with: hermes gateway install", Colors.DIM))
+        print(color("                    sudo hermes gateway install --system  # Linux servers", Colors.DIM))
         print()
 
 
@@ -120,7 +121,8 @@ def cron_status():
         print(color("✗ Gateway is not running — cron jobs will NOT fire", Colors.RED))
         print()
         print("  To enable automatic execution:")
-        print("    hermes gateway install    # Install as system service (recommended)")
+        print("    hermes gateway install    # Install as a user service")
+        print("    sudo hermes gateway install --system  # Linux servers: boot-time system service")
         print("    hermes gateway            # Or run in foreground")
 
     print()

hermes_cli/main.py

@@ -2313,7 +2313,7 @@ Examples:
     hermes gateway                Run messaging gateway
     hermes -s hermes-agent-dev,github-auth
     hermes -w                     Start in isolated git worktree
-    hermes gateway install        Install as system service
+    hermes gateway install        Install gateway background service
     hermes sessions list          List past sessions
     hermes sessions browse        Interactive session picker
     hermes sessions rename ID T   Rename/title a session

website/docs/guides/daily-briefing-bot.md

@@ -29,7 +29,8 @@ Before starting, make sure you have:
 - **Hermes Agent installed** — see the [Installation guide](/docs/getting-started/installation)
 - **Gateway running** — the gateway daemon handles cron execution:
   ```bash
-  hermes gateway install   # Install as system service (recommended)
+  hermes gateway install   # Install as a user service
+  sudo hermes gateway install --system   # Linux servers: boot-time system service
   # or
   hermes gateway           # Run in foreground
   ```
@@ -242,10 +243,12 @@ Make sure the scheduler is actually running:
 hermes cron status
 ```
 
-If the gateway isn't running, your jobs won't execute. Install it as a system service for reliability:
+If the gateway isn't running, your jobs won't execute. Install it as a background service for reliability:
 
 ```bash
 hermes gateway install
+# or on Linux servers
+sudo hermes gateway install --system
 ```
 
 ## Going Further

website/docs/guides/team-telegram-assistant.md

@@ -143,12 +143,13 @@ For a persistent deployment that survives reboots:
 
 ```bash
 hermes gateway install
+sudo hermes gateway install --system   # Linux only: boot-time system service
 ```
 
-This creates a **systemd** service (Linux) or **launchd** service (macOS) that runs automatically.
+This creates a background service: a user-level **systemd** service on Linux by default, a **launchd** service on macOS, or a boot-time Linux system service if you pass `--system`.
 
 ```bash
-# Linux — manage the service
+# Linux — manage the default user service
 hermes gateway start
 hermes gateway stop
 hermes gateway status
@@ -158,6 +159,11 @@ journalctl --user -u hermes-gateway -f
 
 # Keep running after SSH logout
 sudo loginctl enable-linger $USER
+
+# Linux servers — explicit system-service commands
+sudo hermes gateway start --system
+sudo hermes gateway status --system
+journalctl -u hermes-gateway -f
 ```
 
 ```bash

website/docs/user-guide/features/cron.md

@@ -156,7 +156,8 @@ What they do:
 **Cron execution is handled by the gateway daemon.** The gateway ticks the scheduler every 60 seconds, running any due jobs in isolated agent sessions.
 
 ```bash
-hermes gateway install     # Install as system service (recommended)
+hermes gateway install     # Install as a user service
+sudo hermes gateway install --system   # Linux: boot-time system service for servers
 hermes gateway             # Or run in foreground
 
 hermes cron list

website/docs/user-guide/messaging/email.md

@@ -80,7 +80,8 @@ EMAIL_HOME_ADDRESS=your@email.com      # Default delivery target for cron jobs
 
 ```bash
 hermes gateway              # Run in foreground
-hermes gateway install      # Install as a system service
+hermes gateway install      # Install as a user service
+sudo hermes gateway install --system   # Linux only: boot-time system service
 ```
 
 On startup, the adapter:

website/docs/user-guide/messaging/index.md

@@ -54,10 +54,12 @@ This walks you through configuring each platform with arrow-key selection, shows
 ```bash
 hermes gateway              # Run in foreground
 hermes gateway setup        # Configure messaging platforms interactively
-hermes gateway install      # Install as systemd service (Linux) / launchd (macOS)
+hermes gateway install      # Install as a user service (Linux) / launchd service (macOS)
-hermes gateway start        # Start the service
+sudo hermes gateway install --system   # Linux only: install a boot-time system service
-hermes gateway stop         # Stop the service
+hermes gateway start        # Start the default service
-hermes gateway status       # Check service status
+hermes gateway stop         # Stop the default service
+hermes gateway status       # Check default service status
+hermes gateway status --system         # Linux only: inspect the system service explicitly
 ```
 
 ## Chat Commands (Inside Messaging)
@@ -188,8 +190,18 @@ journalctl --user -u hermes-gateway -f
 
 # Enable lingering (keeps running after logout)
 sudo loginctl enable-linger $USER
+
+# Or install a boot-time system service that still runs as your user
+sudo hermes gateway install --system
+sudo hermes gateway start --system
+sudo hermes gateway status --system
+journalctl -u hermes-gateway -f
 ```
 
+Use the user service on laptops and dev boxes. Use the system service on VPS or headless hosts that should come back at boot without relying on systemd linger.
+
+Avoid keeping both the user and system gateway units installed at once unless you really mean to. Hermes will warn if it detects both because start/stop/status behavior gets ambiguous.
+
 ### macOS (launchd)
 
 ```bash

website/docs/user-guide/messaging/signal.md

@@ -127,7 +127,8 @@ Then start the gateway:
 
 ```bash
 hermes gateway              # Foreground
-hermes gateway install      # Install as a system service
+hermes gateway install      # Install as a user service
+sudo hermes gateway install --system   # Linux only: boot-time system service
 ```
 
 ---

website/docs/user-guide/messaging/slack.md

@@ -168,7 +168,8 @@ Then start the gateway:
 
 ```bash
 hermes gateway              # Foreground
-hermes gateway install      # Install as a system service
+hermes gateway install      # Install as a user service
+sudo hermes gateway install --system   # Linux only: boot-time system service
 ```
 
 ---

website/docs/user-guide/messaging/whatsapp.md

@@ -101,7 +101,8 @@ Then start the gateway:
 
 ```bash
 hermes gateway              # Foreground
-hermes gateway install      # Install as a system service
+hermes gateway install      # Install as a user service
+sudo hermes gateway install --system   # Linux only: boot-time system service
 ```
 
 The gateway starts the WhatsApp bridge automatically using the saved session.