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. Folder03-Privatew 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-Privatenie trafia na serwer. Klonujemy repo bez tego folderu (sparse checkout), a dzięki--filter=blob:noneserwer 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ż opcjadocker_extra_args(dowolne flagidocker run), ale Hermes je dodatkowo waliduje.docker_volumesto 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.yamlustawienia sekcjiterminal:bywają rozrzucone między długimi blokami komentarzy (np.docker_imagepod nagłówkiem „Browser Tool Configuration”). Liczy się wcięcie, a nie komentarze, dlatego wartości sprawdzamy przezhermes 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 w04-Wiki/,index.md,log.mdi00-Inbox/(zasady zCLAUDE.md), - cron na serwerze:
git pull --rebase→ commitwiki: …→ push, - plan na konflikty, gdy Ty i agent edytujecie to samo,
- agent nie może zmieniać
CLAUDE.mdaniAGENTS.md. W Hermesie zmiany plików z instrukcjami i tak wymagają zatwierdzenia człowieka (protected_instruction_files), - uzgodnienie wbudowanych skilli
llm-wikiiobsidianz Twoim schematem.
Weryfikacja rozdziału
- Klucz
vault_deploydodany jako deploy key tylko do odczytu. -
ssh -T github-vaultwita Twoje repo. -
/srv/vaultistnieje i nie ma w nim03-Private. -
crontab -lpokazuje odświeżanie co 5 minut (i nie zniknęły inne zadania). -
hermes config get terminal.docker_volumespokazuje listę z/srv/vault:/vault:ro. - Test:
lsdziała,03-Privatenie istnieje,touchzwraca „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.