9

Rozdział 9 z 11

Podłączenie agenta Hermes na VPS (tylko do odczytu)

Opublikowany

Agent na serwerze dostaje dostęp do „drugiego mózgu" tylko do odczytu: osobny deploy key, klon bez folderu prywatnego, odświeżanie co 5 minut i montowanie w piaskownicy Docker. Sprawdzone na żywo na Hermes v0.22.2 — z prawdziwymi wynikami testów.

Czego się nauczysz

  • Piaskownica nie widzi serwera
  • Deploy key tylko do odczytu
  • Sparse checkout bez 03-Private
  • Odświeżanie cronem
  • docker_volumes i test izolacji
  • Pamięć Hermesa i wbudowane skille

Rozdział 9: Podłączenie agenta Hermes na VPS (tylko do odczytu)

Twój agent AI na serwerze (u nas Hermes, z tutoriala „Hermes Agent na VPS”) działa 24/7 i odpowiada Ci np. przez Telegram. W tym rozdziale dajemy mu dostęp do „drugiego mózgu”: na razie tylko do odczytu. Hermes będzie mógł odpowiadać na pytania o Twoją wiedzę i projekty, ale niczego nie zmieni.

Po tym rozdziale Hermes na VPS czyta aktualną wersję vaulta (odświeżaną co 5 minut) i odpowiada zgodnie ze schematem CLAUDE.md. Folder 03-Private w ogóle nie trafia na serwer.

Wymagania: działający Hermes z izolacją Docker (rozdziały 1–6 tutoriala „Hermes Agent na VPS”) oraz vault na GitHubie (Rozdział 7). Przewodnik sprawdziliśmy na Hermes Agent v0.22.2 na Hostinger KVM 2 (Ubuntu 24.04), obok działającej strony produkcyjnej.


Najważniejsze: piaskownica nie widzi serwera

Hermes wykonuje polecenia w piaskownicy Docker, czyli w osobnym kontenerze, który nie widzi plików serwera. To chroni Twoją stronę. Oznacza jednak, że samo sklonowanie vaulta na VPS nie wystarczy. Trzeba świadomie udostępnić folder piaskownicy, i to w trybie tylko do odczytu.


Dwa etapy

Etap Co agent może Ryzyko
1. Czytanie (ten rozdział) czyta bazę i odpowiada na pytania minimalne: nic nie może zmienić
2. Pisanie (w przyszłości) sam robi ingest, a zmiany wracają do Obsidiana konflikty z Twoimi edycjami, więcej konfiguracji

Jak to działa

Mac (Obsidian + wtyczka Git)  ──push──►  GitHub (prywatne repo)
                                              │
                                   co 5 min git pull (cron)
                                              ▼
VPS: /srv/vault  ──tylko do odczytu──►  piaskownica Hermesa: /vault

Dwa dodatkowe zabezpieczenia:

  • 03-Private nie trafia na serwer. Klonujemy repo bez tego folderu (sparse checkout), a dzięki --filter=blob:none serwer nie pobiera nawet treści tych plików.
  • Historia Git leży osobno (/srv/vault.git) i nie trafia do piaskownicy. Agent widzi tylko aktualne pliki.

Krok 1 — Klucz dostępu do repo 🖥️

Na serwerze wygeneruj osobny klucz tylko dla vaulta. Nie używaj klucza, którym serwer pobiera kod strony:

ssh-keygen -t ed25519 -f ~/.ssh/vault_deploy -N "" -C "hermes-vps-vault"
cat ~/.ssh/vault_deploy.pub

Druga komenda pokaże klucz publiczny (ssh-ed25519 …). Klucz publiczny można bezpiecznie pokazać i skopiować.


Krok 2 — Deploy key tylko do odczytu 📱 lub 💻

Deploy key to klucz, który ma dostęp do jednego repozytorium. Dodaj go jedną z dwóch dróg.

W przeglądarce: repo na GitHubie → Settings → Deploy keys → Add deploy key, wklej klucz, tytuł np. hermes-vps (read-only), i nie zaznaczaj „Allow write access”.

Albo z komputera, zapisując klucz do pliku vault_deploy.pub:

gh repo deploy-key add vault_deploy.pub --repo TWOJ_LOGIN/moja-baza --title "hermes-vps (read-only)"

Bez flagi --allow-write klucz jest tylko do odczytu.


Krok 3 — Skrót do GitHuba 🖥️

Żeby klucz vaulta nie mieszał się z innymi kluczami na serwerze:

cat >> ~/.ssh/config <<'EOF'
Host github-vault
  HostName github.com
  User git
  IdentityFile ~/.ssh/vault_deploy
  IdentitiesOnly yes
EOF

Test (jeśli pojawi się pytanie o zaufanie do hosta, wpisz yes; gdy serwer już wcześniej łączył się z GitHubem, np. przy deployu strony, pytania nie będzie):

ssh -T github-vault

Oczekiwany rezultat: Hi TWOJ_LOGIN/moja-baza! You've successfully authenticated…


Krok 4 — Pobranie vaulta bez prywatnego folderu 🖥️

git clone --no-checkout --filter=blob:none --separate-git-dir=/srv/vault.git git@github-vault:TWOJ_LOGIN/moja-baza.git /srv/vault
cd /srv/vault && git sparse-checkout set --no-cone '/*' '!/03-Private/' && git checkout main && ls
Fragment Działanie
--no-checkout najpierw tylko pobiera repo, bez plików
--filter=blob:none treść plików pobiera dopiero wtedy, gdy są potrzebne
--separate-git-dir historia w /srv/vault.git, osobno od plików
sparse-checkout set … '!/03-Private/' wszystko oprócz folderu prywatnego

Oczekiwany rezultat: pierwsza komenda pobiera tylko strukturę i historię (u nas ok. 10 KiB), druga dociąga treść plików i wypisuje listę:

00-Inbox  01-Projects  02-Hermes  04-Wiki  05-Journal  06-Sources  90-Templates  99-Attachments  AGENTS.md  CLAUDE.md  Start.md  _scripts  index.md  log.md

Nie ma tu 03-Private. Sprawdź jeszcze, że folder prywatny nie istnieje, a historia leży osobno:

ls /srv/vault/03-Private; cat /srv/vault/.git; cd ~
ls: cannot access '/srv/vault/03-Private': No such file or directory
gitdir: /srv/vault.git

W /srv/vault zamiast folderu .git jest plik .git ze wskazaniem na /srv/vault.git. Dzięki temu historia (w której są też dawne wersje plików) nie trafi do piaskownicy.


Krok 5 — Odświeżanie co 5 minut 🖥️

( crontab -l 2>/dev/null; echo '*/5 * * * * cd /srv/vault && nice -n 19 ionice -c3 git pull --ff-only -q >> /var/log/vault-pull.log 2>&1' ) | crontab -
crontab -l

nice i ionice nadają najniższy priorytet (jak „klatka” z tutoriala Hermesa), więc odświeżanie nie przeszkodzi stronie. Błędy trafią do /var/log/vault-pull.log.

Komenda dopisuje zadanie do istniejących. Jeśli masz w cronie np. backup bazy z tutoriala CI/CD, zostanie nietknięty:

0 3 * * * /var/www/factorycode/docker/backup-db.sh >> /var/log/factorycode-backup.log 2>&1
*/5 * * * * cd /srv/vault && nice -n 19 ionice -c3 git pull --ff-only -q >> /var/log/vault-pull.log 2>&1

Próbne odświeżenie od ręki:

cd /srv/vault && git pull --ff-only && git log --oneline -3; cd ~

Oczekiwane: Already up to date. i ostatnie commity Twojego vaulta.


Krok 6 — Udostępnienie vaulta piaskownicy 🖥️

Hermes ma do tego wbudowaną opcję terminal.docker_volumes: listę folderów montowanych w piaskownicy, w formacie folder_na_serwerze:folder_w_piaskownicy[:ro]. Hermes zamienia każdy wpis na zwykłe -v Dockera.

Dlaczego nie docker_extra_args? W przykładowej konfiguracji Hermesa jest też opcja docker_extra_args (dowolne flagi docker run), ale Hermes je dodatkowo waliduje. docker_volumes to oficjalna droga właśnie do montowania folderów. Sprawdziliśmy to w kodzie Hermesa v0.22.2 (tools/environments/docker.py).

6a. Sprawdź obecne ustawienia

for k in backend docker_image container_cpu container_memory docker_volumes; do echo -n "terminal.$k = "; hermes config get terminal.$k 2>&1 | tail -1; done

U nas (po rozdziale 5 tutoriala Hermesa):

terminal.backend = docker
terminal.docker_image = python:3.11-slim
terminal.container_cpu = 1
terminal.container_memory = 2048
terminal.docker_volumes = []

Nie przejmuj się położeniem w pliku. W config.yaml ustawienia sekcji terminal: bywają rozrzucone między długimi blokami komentarzy (np. docker_image pod nagłówkiem „Browser Tool Configuration”). Liczy się wcięcie, a nie komentarze, dlatego wartości sprawdzamy przez hermes config get, a nie wzrokiem w pliku.

6b. Ustaw montowanie

hermes config set terminal.docker_volumes '["/srv/vault:/vault:ro"]'
✓ Set terminal.docker_volumes = ['/srv/vault:/vault:ro'] in /root/.hermes/config.yaml

Sprawdź, że zapisało się jako lista. Hermes ignoruje docker_volumes, które nie jest listą:

hermes config get terminal.docker_volumes; grep -n -A2 "^  docker_volumes" ~/.hermes/config.yaml
  - /srv/vault:/vault:ro
590:  docker_volumes:
591-    - /srv/vault:/vault:ro
592-browser:

docker_volumes: jest wcięte dwiema spacjami (należy do terminal:), a pod nim jest element listy - …. :ro oznacza tylko do odczytu.

6c. Restart dashboardu i piaskownicy

Działający Hermes i istniejąca piaskownica mają jeszcze starą konfigurację. Najpierw sprawdź, co działa:

pgrep -af hermes
docker ps --format '{{.Names}}  {{.Image}}  {{.Status}}'

U nas działał dashboard z rozdziału 8 tutoriala Hermesa (w sesji tmux hermes) i piaskownica hermes-… na obrazie python:3.11-slim. Zatrzymaj dashboard:

hermes dashboard --stop; sleep 3; hermes dashboard --status

Usuń starą piaskownicę. Usuwasz tylko kontener hermes-…, nigdy kontenerów strony:

docker rm -f hermes-XXXXXXXX

Uruchom dashboard ponownie, tak jak wcześniej (tmux + klatka):

tmux kill-session -t hermes 2>/dev/null; tmux new-session -d -s hermes 'export PATH=/root/.local/bin:$PATH; systemd-run --scope -p CPUQuota=100% -p MemoryMax=4G hermes dashboard --no-open'
sleep 10; hermes dashboard --status

Oczekiwane: 1 hermes dashboard/serve process(es) running (dalej jest długa linia kodu uruchamiającego Pythona; to normalne). Stały token dashboardu leży w ~/.hermes/.env, więc panel w przeglądarce i aplikacja Desktop łączą się po restarcie bez zmian.

Jeśli nie używasz dashboardu ani Telegrama, ten krok sprowadza się do usunięcia starej piaskownicy. Nowa powstanie sama przy pierwszym poleceniu agenta, już z /vault.


Krok 7 — Test 🖥️

Uruchom Hermesa w klatce:

systemd-run --scope -p CPUQuota=100% -p MemoryMax=4G hermes

Poproś go (każde polecenie zatwierdź):

Wykonaj po kolei: ls /vault, potem ls /vault/03-Private, potem touch /vault/test.txt. Pokaż dokładne wyniki.
Polecenie Oczekiwany wynik Co to dowodzi
ls /vault lista folderów vaulta agent widzi bazę ✅
ls /vault/03-Private No such file or directory prywatne są poza serwerem ✅
touch /vault/test.txt Read-only file system agent nic nie zmieni ✅

Tak to wyglądało u nas (fragment odpowiedzi Hermesa):

2. ls /vault/03-Private
    ls: cannot access '/vault/03-Private': No such file or directory
3. touch /vault/test.txt
    touch: cannot touch '/vault/test.txt': Read-only file system

To pierwsze polecenie agenta po restarcie, więc dopiero teraz powstaje nowa piaskownica, już z montowaniem /vault. Może to potrwać kilka sekund dłużej niż zwykle.

Teraz test samej bazy wiedzy (nie wychodź z czatu):

Przeczytaj /vault/AGENTS.md, /vault/CLAUDE.md i /vault/index.md. Potem odpowiedz zgodnie z tymi zasadami: co wiem o LLM Wiki? Podaj, na których stronach wiki opierasz odpowiedź.

Dobra odpowiedź:

  • czyta pliki w kolejności AGENTS.md → CLAUDE.md → index.md, a potem tylko pasujące strony (llm-wiki, karpathy-llm-wiki, rag…);
  • przy każdym twierdzeniu ma odnośnik [[...]];
  • wymienia strony, na których się opiera, i zaznacza, czego w bazie nie ma;
  • nie próbuje niczego zapisać. U nas Hermes sam dopisał: „Niczego nie zapisywałem ani nie zmieniałem — /vault jest zamontowany tylko do odczytu”.

Krok 8 — Trwała pamięć agenta 🤖

Hermes ma pamięć między rozmowami. W tej samej rozmowie napisz:

Zapamiętaj na stałe: moja baza wiedzy jest w /vault (tylko do odczytu, odświeżana co 5 minut z GitHuba). Zanim odpowiesz na pytanie o moją wiedzę lub projekty, przeczytaj /vault/CLAUDE.md i /vault/index.md i trzymaj się tych zasad. Nie próbuj zapisywać w /vault.

Na liście narzędzi zobaczysz wpis do pamięci, np.:

┊ 🧠 memory    +user: "Baza wiedzy … jest w /vault, tylko do odczytu, odświeżana co 5 minut z GitHuba. …"

Hermes zapisuje to w profilu użytkownika, który dołącza do każdej kolejnej rozmowy.


Krok 9 — Sprawdzenie w nowej rozmowie 🤖

Pamięć sprawdza się dopiero w nowej rozmowie. Wyjdź (/quit), uruchom Hermesa ponownie i zapytaj bez podawania ścieżki:

Co wiem o RAG?

U nas Hermes sam sięgnął do bazy:

┊ 📖 read      CLAUDE.md
┊ 📖 read      index.md
┊ 📖 read      rag.md
┊ 📖 read      llm-wiki.md
┊ 📖 read      karpathy-llm-wiki.md

Odpowiedział z odnośnikami [[rag]], [[llm-wiki]], [[karpathy-llm-wiki]] i dopisał, czego w notatkach brakuje (np. embeddingów i baz wektorowych). Tak ma działać query z Rozdziału 6, tylko że teraz na serwerze.

Od teraz możesz pytać o swoją bazę także z panelu w przeglądarce (dashboard), a po skonfigurowaniu bramki również z telefonu przez Telegram. To ten sam agent i ta sama pamięć.


Wbudowane skille Hermesa a Twój schemat

Podczas testów Hermes sam ładował swoje wbudowane umiejętności (skills) o nazwach llm-wiki i obsidian:

┊ 📚 skill     llm-wiki
┊ 📚 skill     obsidian

To ogólne instrukcje Hermesa dotyczące pracy z takimi bazami. W naszych testach Hermes i tak trzymał się Twojego CLAUDE.md, ale skille mogą mieć inne konwencje (np. inne nazwy folderów). Dopóki Hermes tylko czyta, nie ma to znaczenia. Przed etapem 2 (pisanie) warto sprawdzić, co w nich jest, i w razie konfliktu wprost napisać agentowi, że CLAUDE.md ma pierwszeństwo.


Etap 2: pisanie (zapowiedź)

Kiedy czytanie działa stabilnie, można pozwolić agentowi pisać. Szkic, który doprecyzujemy:

  • deploy key z prawem zapisu,
  • montowanie bez :ro; agent pisze tylko w 04-Wiki/, index.md, log.md i 00-Inbox/ (zasady z CLAUDE.md),
  • cron na serwerze: git pull --rebase → commit wiki: … → push,
  • plan na konflikty, gdy Ty i agent edytujecie to samo,
  • agent nie może zmieniać CLAUDE.md ani AGENTS.md. W Hermesie zmiany plików z instrukcjami i tak wymagają zatwierdzenia człowieka (protected_instruction_files),
  • uzgodnienie wbudowanych skilli llm-wiki i obsidian z Twoim schematem.

Weryfikacja rozdziału

  • Klucz vault_deploy dodany jako deploy key tylko do odczytu.
  • ssh -T github-vault wita Twoje repo.
  • /srv/vault istnieje i nie ma w nim 03-Private.
  • crontab -l pokazuje odświeżanie co 5 minut (i nie zniknęły inne zadania).
  • hermes config get terminal.docker_volumes pokazuje listę z /srv/vault:/vault:ro.
  • Test: ls działa, 03-Private nie istnieje, touch zwraca „Read-only file system”.
  • Hermes odpowiada na pytanie z bazy z odnośnikami [[...]].
  • W nowej rozmowie Hermes sam czyta /vault (pamięć działa).

Częste problemy

Objaw Co zrobić
ssh -T github-vault: Permission denied deploy key nie dodany albo dodany do innego repo
w /var/log/vault-pull.log: Not possible to fast-forward ktoś zmienił pliki w /srv/vault na serwerze; przywróć wersję z GitHuba: cd /srv/vault && git reset --hard origin/main
Hermes: /vault: No such file or directory piaskownica ma starą konfigurację: docker rm -f hermes-…; sprawdź hermes config get terminal.docker_volumes (musi być lista)
docker_volumes zapisało się jako tekst w cudzysłowie popraw ręcznie w nano ~/.hermes/config.yaml: docker_volumes: i pod spodem - /srv/vault:/vault:ro
Hermes w nowej rozmowie odpowiada z ogólnej wiedzy powtórz krok 8; zapytaj go, co ma zapisane w pamięci
Hermes próbuje zapisać w /vault nic się nie stanie (read-only), ale przypomnij mu zasadę z kroku 8

Podsumowanie

  • ✅ Serwer pobiera vault osobnym kluczem, który ma dostęp tylko do odczytu jednego repo.
  • ✅ Folder prywatny i historia Git nie trafiają do agenta.
  • ✅ Vault odświeża się sam co 5 minut.
  • ✅ Vault jest zamontowany w piaskownicy przez docker_volumes, tylko do odczytu.
  • ✅ Hermes odpowiada z bazy z odnośnikami i pamięta o niej w każdej nowej rozmowie.

W następnym rozdziale zbieramy zasady bezpieczeństwa, codzienne utrzymanie i rozwiązania typowych problemów.

Dalej: Rozdział 10 — Bezpieczeństwo, utrzymanie i problemy.

Narzędzia / paczki

Hermes Agent SSH deploy key git sparse-checkout cron docker_volumes

Spis treści