mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
* feat(docker): publish nousresearch/hermes-sandbox:desktop for terminal backends
The terminal backends (docker, modal, daytona, singularity) all default to
nikolaik/python-nodejs:python3.11-nodejs20, a bare Python+Node base. For Bot
Screen, computer_use and the browser to run INSIDE that sandbox instead of on
the gateway host, the sandbox image needs the display stack.
docker/sandbox-desktop.Dockerfile is that base plus:
- the everyday tools it lacked (jq, ripgrep, fd, tmux, less, nano, vim,
zip, rsync, tree, procps, htop, sudo for the base's uid-1000 `pn`)
- the exact package set the Hermes -desktop image installs (TigerVNC,
Xfce components, dbus, xauth, fonts)
- Playwright's headed Chromium (same build as the -desktop image)
- cua-driver 0.28.2 from its pinned release tarball
No Hermes inside; the default user stays root like the base so nothing
changes for people who just switch docker_image. Desktop processes run as
`pn`. 4.27 GB on amd64.
docker.yml gains a `sandbox` variant with its own cache scope and repository
(nousresearch/hermes-sandbox:desktop, :main-desktop, :<release>-desktop);
the docker-integration suite is skipped for it (no Hermes to test) and
docker/sandbox-desktop-smoke.sh runs instead: as `pn`, every launcher and
cua-driver binary resolves, the real launcher.sh publishes :20, the RFB
socket completes the 3.8 handshake relayed over `docker exec -i` stdio, and
a headed Chromium maps a window on that display. hadolint lints the new
Dockerfile in docker-lint.yml.
* feat(docker): sandbox desktop base on python3.13-nodejs26
Matches the Hermes image (Python 3.13 / Node 26) and the top of requires-python;
the default docker_image tag it inherited was Python 3.11 / Node 20. Same pn
uid 1000, Debian 13; smoke (launcher, RFB relay, headed Chromium) passes.
* feat(docker): bake agent-browser into hermes-sandbox:desktop
The browser tools drive the agent-browser CLI; when the browser follows the
terminal backend that CLI has to exist inside the sandbox. Pinned to the same
^0.26.0 range the gateway resolves, --ignore-scripts like the gateway's npx path.
* feat(bot_desktop): the screen, computer_use and the browser follow the terminal backend
A user who sandboxes `terminal` (docker/ssh/singularity) had the agent's
screen, cua-driver and Chromium running on the gateway HOST beside that
sandbox: Bot Screen gave a headless host a display, the Xfce panel carries
xfce4-terminal, and `computer_use` could open a shell outside the boundary
the sandbox exists for.
Now the desktop lives where the terminal lives:
- tools/environments/streams.py: one primitive per spawn-per-call backend, the
local argv prefix that runs its remainder inside the sandbox with stdio open
(`docker exec -i`, `ssh`, `apptainer exec`). SDK backends (modal, daytona,
vercel) have none and report so.
- tools/bot_desktop/sandbox_host.py: launcher.sh runs inside the sandbox as
the image's `pn`; the pane's RFB bytes ride a 12-line python relay over that
prefix; `cua-driver mcp` is the prefix + the sandbox image's own driver.
- tools/bot_desktop/placement.py + `bot_desktop.placement` (auto|terminal|
gateway). `auto` follows the backend; a sandbox that cannot host a screen
REFUSES with the opt-in named instead of silently using the host.
- runtime.start/stop/status/published_env branch on placement; the pane,
lease, epoch fencing and CLI are unchanged.
- cua_backend: the MCP invocation is the sandbox one when the screen is
there; the host driver's runtime contract is irrelevant then; check_fn is
true under a terminal placement without a host binary.
- browser_tool_session: agent-browser invocations are wrapped in the prefix
with the daemon, socket dir and profile inside the sandbox; screenshots are
fetched back so MEDIA: paths keep working; recycle closes the sandbox
daemon.
- web_routers/display.py: the bridge pumps a relay's stdio when the screen is
in a sandbox, a unix socket otherwise.
Live on docker with nousresearch/hermes-sandbox:desktop: start/observe/RFB
handshake through the dashboard bridge, human takeover fences the agent
(HumanHasControl) and keystrokes reach the sandbox Xvnc, handback restores,
three start/stop rounds leave zero desktop processes; computer_use capture
and list_windows see only the sandbox's Xfce; browser_navigate/snapshot/
vision run with Chromium and agent-browser inside the container and zero
host processes on the bot profile; modal + auto refuses naming the opt-in.
* feat(desktop): Screen pane shows where a sandbox-placed screen runs; Install is host-only
DesktopStatus gains placement ('gateway' | 'terminal:<backend>'). A sandbox
image lacking the stack is a blocker naming hermes-sandbox:desktop, shown in
place of Start; install_command stays None there because the pane's Install
button runs the package manager on the gateway host, the wrong machine, and
display.install refuses for the same reason. The pane header carries
'Screen runs inside the docker sandbox, with the terminal' (4 locales).
* fix(bot_desktop): "is the screen in the sandbox" is a disk check on hot paths, never a config read
Every browser command and CUA spawn asked in_sandbox(), which resolves placement by
loading config, which initializes HERMES_HOME. Under a test's fake home that raised
HomeInitializationError from _run_browser_command; on a real host it read config per
click. Hot paths now ask sandbox_screen_running(): the start marker on disk, written
only by a sandbox start. Policy (in_sandbox) stays for start/install, where config is
the question. display.observe gates on "an RFB endpoint exists" for either placement.
* test(moa): late-accounting sink test asserts the wedged slot's row, not sink order
Under CI load the poll loop can see the interrupt before collecting the fast slot, so the
fast slot also arrives late and first; the test then failed on sink_calls[0]. The
contract is that the wedged slot's real usage reaches the sink.
* chore: retrigger CI (zero-job dispatch failure, auto-heal)
* fix(bot_desktop): a sandbox that died under a live screen fails loudly, never falls to the host
sandbox_screen_running() drops a start marker whose terminal environment is no longer
registered (stale after a process restart). When the environment object outlives its
container, the browser's sandbox wrap now checks the published DISPLAY and raises
"the screen inside the terminal backend's sandbox is gone; start it again" instead of
KeyError('AGENT_BROWSER_PROFILE'). Live: fresh sandbox navigate ok; docker rm -f the
container; next navigate returns that error; zero host Chromium either way.
* feat(terminal): nousresearch/hermes-sandbox:desktop is the default container sandbox
Every container backend (docker, modal, daytona, singularity) now defaults to the
sandbox image with the desktop stack, so Bot Screen, computer_use and the browser
run inside the sandbox for everyone who never chose an image; Python 3.13 / Node 26
match the Hermes image. One constant (DEFAULT_SANDBOX_IMAGE) replaces six copies of
the old literal. Migration 47 moves saved configs still holding the OLD default and
never touches an image the user pinned. Docker reuse recreates a container built
from another image, or the flip would silently never take effect for anyone with a
persisted container (live: old container removed, new one on 3.13 / Node 26 with
Xvnc, cua-driver, agent-browser present).
* chore: retrigger CI (zero-job dispatch failure)
* chore: retrigger CI (zero-job dispatch failure, auto-heal)
* chore: retrigger CI (zero-job dispatch failure, auto-heal)
* chore(config): template stamps v47 and shows the new default sandbox image
The template is what install.sh / docker / doctor --fix seed; a stamp behind
DEFAULT_CONFIG makes every fresh install migrate on first run.
* feat(sandbox): the default image change is a decision, not a surprise
A persisted Docker sandbox on another image is kept when docker_image is unset;
only a written docker_image (an explicit pin) recreates it. The pin verdict
travels as TERMINAL_DOCKER_IMAGE_PINNED through both terminal bridges (process
env and per-profile scope) and the container-config allowlist.
Approval surfaces, all through hermes_cli.sandbox_image_switch: the interactive
CLI asks once at startup (y = pin the new image, n = pin the current one, Enter =
ask later); the Screen pane shows the same choice with Switch / Keep buttons via
display.switchSandboxImage; `hermes config set terminal.docker_image …` is the
same answer from any shell. Gateways and cron never decide: they keep the sandbox
and log the notice.
Migration 47 now unsets a saved image equal to the OLD default instead of
rewriting it to the new one — that value was the template copied, not a pin, and
rewriting it would have made the runtime recreate existing sandboxes unasked.
Modal restores its snapshot and Daytona reuses its labeled sandbox regardless of
the configured image, so existing sandboxes there were already untouched.
* fix(config): both plain defaults that preceded the desktop sandbox image are template copies
main pinned nikolaik/python-nodejs:python3.14-nodejs22 (cd0f97f833) without a migration;
a saved config holding either literal is unset by migration 47, so it follows the default
and existing sandboxes get the keep-or-switch decision instead of a silent recreate.
* ci(docker): build the sandbox image on release/dispatch, not every main push
Leaves docker.yml exactly as on main. The sandbox image carries no Hermes code,
so two 4 GB multi-arch builds per merge bought nothing. sandbox-image.yml builds
and smokes on a PR that edits its own Dockerfile/smoke, and publishes only on a
release or a manual dispatch with publish=true. Stable tag stays :desktop.
* fix(config): keep main's config.py/config_defaults.py edits under the sandbox-image delta
The rebase resolved both files wholesale with the branch side, dropping main's move to
hermes_yaml (the 3.14 runtime venv has no PyYAML) and the 3.14 base pin. This is main's
version plus exactly the branch's own changes: DEFAULT_SANDBOX_IMAGE, the pin verdict in the
env bridge, placement defaults and the v47 stamp.
* test: sandbox-image tests read config.yaml through hermes_yaml (no PyYAML on the 3.14 runtime)
* fix(bot_desktop): read the sandbox marker BOM-tolerantly (windows footgun lint)
* fix(bot_desktop): placement is the authority; sandbox screen survives restarts
Review findings on the sandbox-hosted Bot Screen, each reproduced live first.
Authority. The browser preflight and the CUA invocation keyed off screen
LIVENESS, so `placement: terminal` with the screen not yet up handed the tool an
unchanged host command. `runtime.tool_placement()` is now the one resolver:
terminal placement starts the sandbox screen on demand (no auto_start opt-in
inside the user's own sandbox), refused placement raises its reason, and neither
ever yields the host. placement.resolve() answers a local backend from env alone
so the common case costs no config load on the spawn path.
Restart. sandbox_screen_running() deleted the marker whenever the process-local
terminal registry was empty, i.e. after every gateway restart, while Xvnc kept
running in the container; stop() then returned False and left it. The marker
now records the owning container; liveness comes from `docker inspect` on it,
stop/status re-attach to the recorded owner (even after the placement setting
moved), and only a container that is gone drops the marker.
SSH. remote_argv emitted `bash -c <script>` as three words; OpenSSH joins them
and the remote login shell ran `bash -c export` and the rest itself. The script
travels as one quoted word for ssh (remote_command knows the backend); docker
and apptainer keep argv.
CDP reach. agent-browser inside the sandbox reports the sandbox's loopback;
the Browser Use harness, browser_exec and the vault supervisor connect from the
host and got connection refused. streams.forward_port() proxies a local port
over the exec stream (same relay as the RFB bridge) and the CDP URL is rewritten
to the local end.
pids limit. --pids-limit 256 counts threads; measured on the desktop image the
desktop stack is 44, one Chromium tab 212, the agent's browser with two tabs
488. Past the cap every further docker exec died with "procReady not received".
Default is 2048 with the measurements in the comment.
Replacement. An approved image switch force-removed the old container before
`docker run` tried the new image; a private tag or registry outage left nothing.
The image is inspected/pulled first and the old container kept on failure.
Desktop integration. The sandbox start never passed the dock's browser launcher
(no Browser icon) and the thumbnail needed a host launcher pid + host ImageGrab
(always None). The dock runs the sandbox's Playwright Chromium on the shared
profile; the thumbnail is grabbed inside the sandbox (Pillow baked into the
image). The browser profile moves from /tmp — a 512 MB tmpfs emptied on every
container stop — to the desktop user's home, so logins follow the container.
Pin provenance. A TERMINAL_DOCKER_IMAGE written in a routed profile's .env is a
pin even when it spells the default; the scope compared values before.
* docs(bot-screen): no literal tmp path in the profile-location note
* fix(bot_desktop): docker inspect liveness probe closes stdin (TUI subprocess guard)
* fix(bot_desktop): adopting a screen the sandbox kept records the marker
Live ssh probe: after the host's state was lost while the sandbox kept its
Xvnc, start() took the idempotent early return (display already published)
and never wrote the host marker, so status/thumbnail/stop lost the screen.
Record the adopted display like a fresh launch.
Docs: what an ssh host of your own must carry, and why a Dockerfile ENV is
not enough for a login session (PLAYWRIGHT_BROWSERS_PATH via /etc/environment).
* docker(sandbox-desktop): login sessions find the browser (PLAYWRIGHT_BROWSERS_PATH via /etc/environment)
* docs(bot-screen): what the Apptainer path inherits from the image and what it does not
* chore(config): sandbox-image migration is 47→48 (main took 47 for compression.threshold_tokens)
* chore: retrigger CI (zero-job dispatch failure, auto-heal)
441 lines
13 KiB
Markdown
441 lines
13 KiB
Markdown
---
|
|
sidebar_position: 4
|
|
title: "Tutorial: Team Telegram Assistant"
|
|
description: "Step-by-step guide to setting up a Telegram bot that your whole team can use for code help, research, system admin, and more"
|
|
---
|
|
|
|
# Set Up a Team Telegram Assistant
|
|
|
|
This tutorial walks you through setting up a Telegram bot powered by Hermes Agent that multiple team members can use. By the end, your team will have a shared AI assistant they can message for help with code, research, system administration, and anything else — secured with per-user authorization.
|
|
|
|
## What We're Building
|
|
|
|
A Telegram bot that:
|
|
|
|
- **Any authorized team member** can DM for help — code reviews, research, shell commands, debugging
|
|
- **Runs on your server** with full tool access — terminal, file editing, web search, code execution
|
|
- **Per-user sessions** — each person gets their own conversation context
|
|
- **Secure by default** — only approved users can interact, with two authorization methods
|
|
- **Scheduled tasks** — daily standups, health checks, and reminders delivered to a team channel
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
Before starting, make sure you have:
|
|
|
|
- **Hermes Agent installed** on a server or VPS (not your laptop — the bot needs to stay running). Follow the [installation guide](../getting-started/installation.md) if you haven't yet.
|
|
- **A Telegram account** for yourself (the bot owner)
|
|
- **An LLM provider configured** — at minimum, an API key for OpenAI, Anthropic, or another supported provider in `~/.hermes/.env`
|
|
|
|
:::tip
|
|
A $5/month VPS is plenty for running the gateway. Hermes itself is lightweight — the LLM API calls are what cost money, and those happen remotely.
|
|
:::
|
|
|
|
---
|
|
|
|
## Step 1: Create a Telegram Bot
|
|
|
|
Every Telegram bot starts with **@BotFather** — Telegram's official bot for creating bots.
|
|
|
|
1. **Open Telegram** and search for `@BotFather`, or go to [t.me/BotFather](https://t.me/BotFather)
|
|
|
|
2. **Send `/newbot`** — BotFather will ask you two things:
|
|
- **Display name** — what users see (e.g., `Team Hermes Assistant`)
|
|
- **Username** — must end in `bot` (e.g., `myteam_hermes_bot`)
|
|
|
|
3. **Copy the bot token** — BotFather replies with something like:
|
|
```
|
|
Use this token to access the HTTP API:
|
|
7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
|
|
```
|
|
Save this token — you'll need it in the next step.
|
|
|
|
4. **Set a description** (optional but recommended):
|
|
```
|
|
/setdescription
|
|
```
|
|
Choose your bot, then enter something like:
|
|
```
|
|
Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.
|
|
```
|
|
|
|
5. **Set bot commands** (optional — gives users a command menu):
|
|
```
|
|
/setcommands
|
|
```
|
|
Choose your bot, then paste:
|
|
```
|
|
new - Start a fresh conversation
|
|
model - Show or change the AI model
|
|
status - Show session info
|
|
help - Show available commands
|
|
stop - Stop the current task
|
|
```
|
|
|
|
:::warning
|
|
Keep your bot token secret. Anyone with the token can control the bot. If it leaks, use `/revoke` in BotFather to generate a new one.
|
|
:::
|
|
|
|
---
|
|
|
|
## Step 2: Configure the Gateway
|
|
|
|
You have two options: the interactive setup wizard (recommended) or manual configuration.
|
|
|
|
### Option A: Interactive Setup (Recommended)
|
|
|
|
```bash
|
|
hermes gateway setup
|
|
```
|
|
|
|
This walks you through everything with arrow-key selection. Pick **Telegram**, paste your bot token, and enter your user ID when prompted.
|
|
|
|
### Option B: Manual Configuration
|
|
|
|
Add these lines to `~/.hermes/.env`:
|
|
|
|
```bash
|
|
# Telegram bot token from BotFather
|
|
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
|
|
|
|
# Your Telegram user ID (numeric)
|
|
TELEGRAM_ALLOWED_USERS=123456789
|
|
```
|
|
|
|
### Finding Your User ID
|
|
|
|
Your Telegram user ID is a numeric value (not your username). To find it:
|
|
|
|
1. Message [@userinfobot](https://t.me/userinfobot) on Telegram
|
|
2. It instantly replies with your numeric user ID
|
|
3. Copy that number into `TELEGRAM_ALLOWED_USERS`
|
|
|
|
:::info
|
|
Telegram user IDs are permanent numbers like `123456789`. They're different from your `@username`, which can change. Always use the numeric ID for allowlists.
|
|
:::
|
|
|
|
---
|
|
|
|
## Step 3: Start the Gateway
|
|
|
|
### Quick Test
|
|
|
|
Run the gateway in the foreground first to make sure everything works:
|
|
|
|
```bash
|
|
hermes gateway
|
|
```
|
|
|
|
You should see output like:
|
|
|
|
```
|
|
[Gateway] Starting Hermes Gateway...
|
|
[Gateway] Telegram adapter connected
|
|
[Gateway] Cron scheduler started (tick every 60s)
|
|
```
|
|
|
|
Open Telegram, find your bot, and send it a message. If it replies, you're in business. Press `Ctrl+C` to stop.
|
|
|
|
### Production: Install as a Service
|
|
|
|
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 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 default user service
|
|
hermes gateway start
|
|
hermes gateway stop
|
|
hermes gateway status
|
|
|
|
# View live logs
|
|
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
|
|
# macOS — manage the service
|
|
hermes gateway start
|
|
hermes gateway stop
|
|
tail -f ~/.hermes/logs/gateway.log
|
|
```
|
|
|
|
:::tip macOS PATH
|
|
The launchd plist captures your shell PATH at install time so gateway subprocesses can find tools like Node.js and ffmpeg. If you install new tools later, re-run `hermes gateway install` to update the plist.
|
|
:::
|
|
|
|
### Verify It's Running
|
|
|
|
```bash
|
|
hermes gateway status
|
|
```
|
|
|
|
Then send a test message to your bot on Telegram. You should get a response within a few seconds.
|
|
|
|
---
|
|
|
|
## Step 4: Set Up Team Access
|
|
|
|
Now let's give your teammates access. There are two approaches.
|
|
|
|
### Approach A: Static Allowlist
|
|
|
|
Collect each team member's Telegram user ID (have them message [@userinfobot](https://t.me/userinfobot)) and add them as a comma-separated list:
|
|
|
|
```bash
|
|
# In ~/.hermes/.env
|
|
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555
|
|
```
|
|
|
|
Restart the gateway after changes:
|
|
|
|
```bash
|
|
hermes gateway stop && hermes gateway start
|
|
```
|
|
|
|
### Approach B: DM Pairing (Recommended for Teams)
|
|
|
|
DM pairing is more flexible — you don't need to collect user IDs upfront. Here's how it works:
|
|
|
|
1. **Teammate DMs the bot** — since they're not on the allowlist, the bot replies with a one-time pairing code:
|
|
```
|
|
🔐 Pairing code: XKGH5N7P
|
|
Send this code to the bot owner for approval.
|
|
```
|
|
|
|
2. **Teammate sends you the code** (via any channel — Slack, email, in person)
|
|
|
|
3. **You approve it** on the server:
|
|
```bash
|
|
hermes pairing approve telegram XKGH5N7P
|
|
```
|
|
|
|
4. **They're in** — the bot immediately starts responding to their messages
|
|
|
|
**Managing paired users:**
|
|
|
|
```bash
|
|
# See all pending and approved users
|
|
hermes pairing list
|
|
|
|
# Revoke someone's access
|
|
hermes pairing revoke telegram 987654321
|
|
|
|
# Clear expired pending codes
|
|
hermes pairing clear-pending
|
|
```
|
|
|
|
:::tip
|
|
DM pairing is ideal for teams because you don't need to restart the gateway when adding new users. Approvals take effect immediately.
|
|
:::
|
|
|
|
### Security Considerations
|
|
|
|
- **Never set `GATEWAY_ALLOW_ALL_USERS=true`** on a bot with terminal access — anyone who finds your bot could run commands on your server
|
|
- Pairing codes expire after **1 hour** and use cryptographic randomness
|
|
- Rate limiting prevents brute-force attacks: 1 request per user per 10 minutes, max 3 pending codes per platform
|
|
- After 5 failed approval attempts, the platform enters a 1-hour lockout
|
|
- All pairing data is stored with `chmod 0600` permissions
|
|
|
|
---
|
|
|
|
## Step 5: Configure the Bot
|
|
|
|
### Set a Home Channel
|
|
|
|
A **home channel** is where the bot delivers cron job results and proactive messages. Without one, scheduled tasks have nowhere to send output.
|
|
|
|
**Option 1:** Use the `/sethome` command in any Telegram group or chat where the bot is a member.
|
|
|
|
**Option 2:** Set it manually in `~/.hermes/.env`:
|
|
|
|
```bash
|
|
TELEGRAM_HOME_CHANNEL=-1001234567890
|
|
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"
|
|
```
|
|
|
|
To find a channel ID, add [@userinfobot](https://t.me/userinfobot) to the group — it will report the group's chat ID.
|
|
|
|
### Configure Tool Progress Display
|
|
|
|
Control how much detail the bot shows when using tools. In `~/.hermes/config.yaml`:
|
|
|
|
```yaml
|
|
display:
|
|
tool_progress: new # off | new | all | verbose
|
|
```
|
|
|
|
| Mode | What You See |
|
|
|------|-------------|
|
|
| `off` | Clean responses only — no tool activity |
|
|
| `new` | Brief status for each new tool call (recommended for messaging) |
|
|
| `all` | Every tool call with details |
|
|
| `verbose` | Full tool output including command results |
|
|
|
|
Users can also change this per-session with the `/verbose` command in chat.
|
|
|
|
### Set Up a Personality with SOUL.md
|
|
|
|
Customize how the bot communicates by editing `~/.hermes/SOUL.md`:
|
|
|
|
For a full guide, see [Use SOUL.md with Hermes](./use-soul-with-hermes.md).
|
|
|
|
```markdown
|
|
# Soul
|
|
You are a helpful team assistant. Be concise and technical.
|
|
Use code blocks for any code. Skip pleasantries — the team
|
|
values directness. When debugging, always ask for error logs
|
|
before guessing at solutions.
|
|
```
|
|
|
|
### Add Project Context
|
|
|
|
If your team works on specific projects, create context files so the bot knows your stack:
|
|
|
|
```markdown
|
|
<!-- ~/.hermes/AGENTS.md -->
|
|
# Team Context
|
|
- We use Python 3.12 with FastAPI and SQLAlchemy
|
|
- Frontend is React with TypeScript
|
|
- CI/CD runs on GitHub Actions
|
|
- Production deploys to AWS ECS
|
|
- Always suggest writing tests for new code
|
|
```
|
|
|
|
:::info
|
|
Context files are injected into every session's system prompt. Keep them concise — every character counts against your token budget.
|
|
:::
|
|
|
|
---
|
|
|
|
## Step 6: Set Up Scheduled Tasks
|
|
|
|
With the gateway running, you can schedule recurring tasks that deliver results to your team channel.
|
|
|
|
### Daily Standup Summary
|
|
|
|
Message the bot on Telegram:
|
|
|
|
```
|
|
Every weekday at 9am, check the GitHub repository at
|
|
github.com/myorg/myproject for:
|
|
1. Pull requests opened/merged in the last 24 hours
|
|
2. Issues created or closed
|
|
3. Any CI/CD failures on the main branch
|
|
Format as a brief standup-style summary.
|
|
```
|
|
|
|
The agent creates a cron job automatically and delivers results to the chat where you asked (or the home channel).
|
|
|
|
### Server Health Check
|
|
|
|
```
|
|
Every 6 hours, check disk usage with 'df -h', memory with 'free -h',
|
|
and Docker container status with 'docker ps'. Report anything unusual —
|
|
partitions above 80%, containers that have restarted, or high memory usage.
|
|
```
|
|
|
|
### Managing Scheduled Tasks
|
|
|
|
```bash
|
|
# From the CLI
|
|
hermes cron list # View all scheduled jobs
|
|
hermes cron status # Check if scheduler is running
|
|
|
|
# From Telegram chat
|
|
/cron list # View jobs
|
|
/cron remove <job_id> # Remove a job
|
|
```
|
|
|
|
:::warning
|
|
Cron job prompts run in completely fresh sessions with no memory of prior conversations. Make sure each prompt contains **all** the context the agent needs — file paths, URLs, server addresses, and clear instructions.
|
|
:::
|
|
|
|
---
|
|
|
|
## Production Tips
|
|
|
|
### Use Docker for Safety
|
|
|
|
On a shared team bot, use Docker as the terminal backend so agent commands run in a container instead of on your host:
|
|
|
|
```bash
|
|
# In ~/.hermes/.env
|
|
TERMINAL_ENV=docker
|
|
TERMINAL_DOCKER_IMAGE=nousresearch/hermes-sandbox:desktop
|
|
```
|
|
|
|
Or in `~/.hermes/config.yaml`:
|
|
|
|
```yaml
|
|
terminal:
|
|
backend: docker
|
|
container_cpu: 1
|
|
container_memory: 5120
|
|
container_persistent: true
|
|
```
|
|
|
|
This way, even if someone asks the bot to run something destructive, your host system is protected.
|
|
|
|
### Monitor the Gateway
|
|
|
|
```bash
|
|
# Check if the gateway is running
|
|
hermes gateway status
|
|
|
|
# Watch live logs (Linux)
|
|
journalctl --user -u hermes-gateway -f
|
|
|
|
# Watch live logs (macOS)
|
|
tail -f ~/.hermes/logs/gateway.log
|
|
```
|
|
|
|
### Keep Hermes Updated
|
|
|
|
From Telegram, send `/update` to the bot — it will pull the latest version and restart. Or from the server:
|
|
|
|
```bash
|
|
hermes update
|
|
hermes gateway stop && hermes gateway start
|
|
```
|
|
|
|
### Log Locations
|
|
|
|
| What | Location |
|
|
|------|----------|
|
|
| Gateway logs | `journalctl --user -u hermes-gateway` (Linux) or `~/.hermes/logs/gateway.log` (macOS) |
|
|
| Cron job output | `~/.hermes/cron/output/{job_id}/{timestamp}.md` |
|
|
| Cron job definitions | `~/.hermes/cron/jobs.json` |
|
|
| Pairing data | `~/.hermes/pairing/` |
|
|
| Session history | `~/.hermes/sessions/` |
|
|
|
|
---
|
|
|
|
## Going Further
|
|
|
|
You've got a working team Telegram assistant. Here are some next steps:
|
|
|
|
- **[Security Guide](../user-guide/security.md)** — deep dive into authorization, container isolation, and command approval
|
|
- **[Messaging Gateway](../user-guide/messaging/index.md)** — full reference for gateway architecture, session management, and chat commands
|
|
- **[Telegram Setup](../user-guide/messaging/telegram.md)** — platform-specific details including voice messages and TTS
|
|
- **[Scheduled Tasks](../user-guide/features/cron.md)** — advanced cron scheduling with delivery options and cron expressions
|
|
- **[Context Files](../user-guide/features/context-files.md)** — AGENTS.md, SOUL.md, and .cursorrules for project knowledge
|
|
- **[Personality](../user-guide/features/personality.md)** — built-in personality presets and custom persona definitions
|
|
- **Add more platforms** — the same gateway can simultaneously run [Discord](../user-guide/messaging/discord.md), [Slack](../user-guide/messaging/slack.md), and [WhatsApp](../user-guide/messaging/whatsapp.md)
|
|
|
|
---
|
|
|
|
*Questions or issues? Open an issue on GitHub — contributions are welcome.*
|