CLI / Desktop Onboarding — Team Hermes

Phase C decision record + member setup guide. H1 outcome: Slack app creation works, but installing the app into the GLOO workspace ("Install to GLOO") is blocked on admin approval. Slack therefore cannot carry the team lane today → CLI + desktop remote-gateway (C2) is the primary path. See "Slack later" at the bottom.

What you're connecting to

• Host: hermes.dev.360.gloo.com (team VM, AWS)
• Software: Hermes Agent v0.21.0 (gateway runs as a systemd service)
• Model: gloo-z-ai-glm-5.3 via the employer Gloo AI platform — you do NOT need your own API key
• Brain: one shared, persistent memory for the whole team. Anything anyone teaches it (preferences, project context) is remembered for everyone. Do not paste secrets, tokens, or personal credentials into chat — they land in the shared brain on a company VM.

Prerequisite for every path: your SSH public key must be on the VM. Send it to Chad once; he adds it to ~ubuntu/.ssh/authorized_keys.

Upstream docs: https://hermes-agent.nousresearch.com/docs (desktop remote backend: User Guide → Desktop → "Connecting to a remote backend"; connection registry: "Connecting Desktop to Many Hermes Instances").

Path A — Desktop app (recommended)

The desktop app (macOS / Windows / Linux) can attach to a Hermes backend on another machine over SSH. It opens the tunnel, starts the backend on the VM on demand, and adopts a session token automatically — no password, no exposed ports. Chats, sessions, and memory all live on the VM.

1. Install

Download the Hermes Desktop installer from https://hermes-agent.nousresearch.com/desktop (or on an existing CLI install run hermes desktop). You do not need to configure a local provider — pick "Choose provider later" in first-run onboarding; your chats run on the VM's provider.

2. Make sure SSH works from your machine

ssh ubuntu@hermes.dev.360.gloo.com   # uses your default key
# first connect: accept the host key. You should land in a shell.
# If you use a non-default key file:
#   ssh -i ~/.ssh/your_key ubuntu@hermes.dev.360.gloo.com
#   (and reference that key below)

If SSH asks nothing and just works, Desktop will work too — it uses the same key. On macOS the app reads your ~/.ssh; if your key has a passphrase, entering it once in the app stores it in the OS keychain.

3. Add the connection

1. Open the app → Settings → Gateways (or click the plug button at the right end of the sidebar profile rail).
2. Scroll to Registered gateways → Add connection → kind SSH.
3. Fill in: - Name: Team VM (any unique name) - SSH host: ubuntu@hermes.dev.360.gloo.com (port 22 default)
4. Save connection, then click Test — it should report Reachable.
5. Select it from the gateway selector in the Sessions sidebar (it shows "connect on demand" until first use — that's by design, not a failure).

4. Chat

Open a new chat (Cmd/Ctrl+N) and talk to it. Status bar should show the backend on the VM. Everything — sessions, memory, skills — lives on the VM.

Useful desktop extras: drag-and-drop files into chat, review pane (Cmd/Ctrl+G) for git work, Cmd/Ctrl+K command palette.

Desktop troubleshooting

• "Reachable" but chat never connects — update the desktop app (Settings → About). Older builds predate the multi-connection stack.
• SSH host key changed (VM rebuilt): ssh-keygen -R hermes.dev.360.gloo.com, then edit/re-test the connection in the app.
• Key not found: confirm ssh ubuntu@hermes.dev.360.gloo.com works in a terminal on the same machine first; Desktop cannot use a key SSH can't.
• Logs: hermes logs gui -f (local desktop log).

Path B — CLI over SSH

No local Hermes install needed — the VM already has one. SSH in and use it.

Interactive session

ssh -t ubuntu@hermes.dev.360.gloo.com hermes

(If your key isn't the default: add -i ~/.ssh/your_key.) You get the interactive chat; sessions/memory are the shared VM ones. Exit with /exit.

One-shot queries

ssh ubuntu@hermes.dev.360.gloo.com \
  'hermes chat -Q --query="Summarize what you remember about project X"'

Notes: -Q suppresses the banner/stats so you get just the answer; use the --query="..." form (a bare -q -Q trips the argument parser).

Recommended: an ssh alias

Add to ~/.ssh/config on your machine:

Host hermes-team
    HostName hermes.dev.360.gloo.com
    User ubuntu
    # IdentityFile ~/.ssh/your_key   # only if non-default

Then it's just ssh -t hermes-team hermes.

CLI troubleshooting

• hermes: command not found over ssh → use the full path: ~/.local/bin/hermes.
• Health check on the VM: hermes status, hermes doctor.

Path C — manual tunnel (debugging only)

The Desktop SSH connection (Path A) does this automatically; manual mode is only for debugging:

ssh -N -L 19119:127.0.0.1:9119 ubuntu@hermes.dev.360.gloo.com
# in another terminal, verify the backend answers through the tunnel:
curl -s http://127.0.0.1:19119/api/status | head -c 200

Expected: JSON with "version":"0.21.0". The backend (hermes serve) on the VM binds loopback only; Desktop's SSH connection starts it on demand over the tunnel (hermes serve --ssh-session-token-file handshake).

Security notes

• The VM exposes only SSH (port 22); your SSH key is the gate. There is deliberately no password-protected HTTP port open to the internet — upstream docs forbid password-gated backends on public hosts, and OAuth gating is unnecessary overhead while SSH works.
• The gateway on the VM runs with full tools (terminal, files, web). Treat it like any shared company system.
• Shared brain reminder: anything told in chat persists for the whole team.

Verification (2026-09-03, from the bee control host)

• One-shot chat over SSH: session_id: 20260903_232720_745f52 → gloo-z-ai-glm-5.3, custom, walrus (model + provider + shared memory word recalled across sessions — memory round-trip intact).
• Backend leg: hermes serve --host 127.0.0.1 --port 9119 on the VM → HERMES_BACKEND_READY port=9119; /api/status returns v0.21.0 JSON.
• Tunnel leg from bee: ssh -L 19119:127.0.0.1:9119 → live /api/status JSON through the tunnel. Test process stopped afterwards (9119 free).
• Full transcript: docs/evidence/t_db1e0be2-c2-onboarding.md.

Slack later

The Slack app Chad created still exists. When GLOO IT admin approves the "Install to GLOO" request, H3 proceeds: bot/app tokens go to the VM env (SLACK_BOT_TOKEN / SLACK_APP_TOKEN, Socket Mode — no public URL needed) per https://hermes-agent.nousresearch.com/docs/user-guide/messaging/slack, and Slack DMs become a third lane alongside desktop/CLI. Nothing about the paths above changes — they keep working.