From 95939a1b5130c4a04bf67eaacbbb7ea7af5bd3f3 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Sat, 14 Mar 2026 21:17:41 -0700 Subject: [PATCH] docs: clarify gateway service scopes (#1378) --- cron/__init__.py | 3 ++- hermes_cli/cron.py | 4 +++- hermes_cli/main.py | 2 +- website/docs/guides/daily-briefing-bot.md | 7 +++++-- .../docs/guides/team-telegram-assistant.md | 10 ++++++++-- website/docs/user-guide/features/cron.md | 3 ++- website/docs/user-guide/messaging/email.md | 3 ++- website/docs/user-guide/messaging/index.md | 20 +++++++++++++++---- website/docs/user-guide/messaging/signal.md | 3 ++- website/docs/user-guide/messaging/slack.md | 3 ++- website/docs/user-guide/messaging/whatsapp.md | 3 ++- 11 files changed, 45 insertions(+), 16 deletions(-) diff --git a/cron/__init__.py b/cron/__init__.py index 31d7bf8e7..2c44cabf6 100644 --- a/cron/__init__.py +++ b/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 diff --git a/hermes_cli/cron.py b/hermes_cli/cron.py index a068d6377..97a225794 100644 --- a/hermes_cli/cron.py +++ b/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() diff --git a/hermes_cli/main.py b/hermes_cli/main.py index 1238d9b6a..5f9356b84 100644 --- a/hermes_cli/main.py +++ b/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 diff --git a/website/docs/guides/daily-briefing-bot.md b/website/docs/guides/daily-briefing-bot.md index 85f11c408..78bfd6909 100644 --- a/website/docs/guides/daily-briefing-bot.md +++ b/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 diff --git a/website/docs/guides/team-telegram-assistant.md b/website/docs/guides/team-telegram-assistant.md index 124f4bf3c..88de9c706 100644 --- a/website/docs/guides/team-telegram-assistant.md +++ b/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 diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.md index dd7d5606f..2d0a4c836 100644 --- a/website/docs/user-guide/features/cron.md +++ b/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 diff --git a/website/docs/user-guide/messaging/email.md b/website/docs/user-guide/messaging/email.md index f6746290b..8f515e851 100644 --- a/website/docs/user-guide/messaging/email.md +++ b/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: diff --git a/website/docs/user-guide/messaging/index.md b/website/docs/user-guide/messaging/index.md index 39c03b74d..d71edafef 100644 --- a/website/docs/user-guide/messaging/index.md +++ b/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 start # Start the service -hermes gateway stop # Stop the service -hermes gateway status # Check service status +hermes gateway install # Install as a user service (Linux) / launchd service (macOS) +sudo hermes gateway install --system # Linux only: install a boot-time system service +hermes gateway start # Start the default service +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 diff --git a/website/docs/user-guide/messaging/signal.md b/website/docs/user-guide/messaging/signal.md index 53bb862ad..e1fd5463b 100644 --- a/website/docs/user-guide/messaging/signal.md +++ b/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 ``` --- diff --git a/website/docs/user-guide/messaging/slack.md b/website/docs/user-guide/messaging/slack.md index 2ff79f351..29a14353a 100644 --- a/website/docs/user-guide/messaging/slack.md +++ b/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 ``` --- diff --git a/website/docs/user-guide/messaging/whatsapp.md b/website/docs/user-guide/messaging/whatsapp.md index af432fb85..eb7414678 100644 --- a/website/docs/user-guide/messaging/whatsapp.md +++ b/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.