Jak wdrożyć agenta Hermes na instancjach Cloud Run

1. Wprowadzenie

Przegląd

W tym module wdrożysz w instancjach Cloud Run w pełni trwałą i bezpieczną instancję agenta Hermes (od Nous Research). Z agentem AI będziesz wchodzić w interakcje za pomocą panelu internetowego Hermes, a jego trwałe miejsce pracy będzie obsługiwane przez Google Cloud Storage.

Hermes obsługuje tryb bramy, który może działać jako usługa Cloud Run z autoskalowaniem, ale pełni też funkcję agenta stanowego, który skanuje umiejętności podczas uruchamiania i obsługuje wykonywanie w tle. Instancje Cloud Run zapewniają długotrwałe, indywidualnie adresowane środowisko, które idealnie nadaje się do tego rodzaju zbioru zadań.

Jakie zadania wykonasz

• Przygotuj zasobnik Cloud Storage do przechowywania stanu i konfiguracji kontenera.
• Utwórz niestandardowy nadzorcę Pythona (run_hermes.py) i skrypt startowy (start_hermes.sh), aby obsługiwać inicjowanie rozruchu.
• Wdróż agenta Hermes za pomocą narzędzia gcloud beta run instances deploy.
• Uzyskaj dostęp do panelu Hermes i uwierzytelnij się w nim.

Czego się nauczysz

• Jak wdrożyć agenta Hermes na instancjach Cloud Run.
• Jak montować zasobniki Cloud Storage w instancjach Cloud Run za pomocą GCSFuse.
• Jak bezpiecznie skonfigurować SQLite i pamięci podręczne, aby ominąć ograniczenia blokowania plików GCSFuse.

2. Konfiguracja i wymagania

Konfiguracja projektu GCP

1. Zaloguj się w konsoli Google Cloud.
2. Utwórz lub wybierz projekt Google Cloud.
3. Sprawdź, czy w projekcie Google Cloud włączone są płatności.

Otwórz Cloud Shell

Aktywuj Google Cloud Shell na pasku narzędzi u góry konsoli Cloud.

Ustawianie projektu i instalowanie wersji beta gcloud

Najpierw ustaw projekt i region jako zmienne środowiskowe.

export PROJECT_ID=<YOUR_PROJECT_ID>
export REGION="us-west2"
export BUCKET_NAME="hermes-state-${PROJECT_ID}"

i skonfiguruj projekt na potrzeby gcloud.

gcloud config set project $PROJECT_ID

Sprawdź, czy komponent beta jest zainstalowany w przypadku gcloud beta run instances:

gcloud components install beta --quiet

Twoja wersja gcloud jest aktualna.

gcloud components updates

Włączanie wymaganych interfejsów Google Cloud API

W Cloud Shell włącz interfejsy Cloud Run API, Cloud Storage API i Secret Manager API:

gcloud services enable \
  run.googleapis.com \
  secretmanager.googleapis.com \
  storage.googleapis.com \
  compute.googleapis.com \
  aiplatform.googleapis.com

3. Utwórz dedykowane konto usługi

Aby zachować zgodność z zasadą jak najmniejszych uprawnień, utwórz dedykowane konto usługi IAM dla agenta Hermes i przyznaj mu uprawnienia niezbędne do wywoływania modeli Vertex AI:

export SERVICE_ACCOUNT_NAME="hermes-sa"
gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME} \
  --display-name="Hermes Service Account"

export SERVICE_ACCOUNT="${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding ${PROJECT_ID} \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/aiplatform.user"

4. Przechowywanie danych logowania w usłudze Secret Manager

Poufne dane logowania, takie jak hasło do panelu, będziemy przechowywać w usłudze Google Cloud Secret Manager, aby Cloud Run mogła bezpiecznie wstrzykiwać je do kontenera podczas uruchamiania.

Wygeneruj bezpieczne losowe hasło do panelu i zapisz je w usłudze Secret Manager:

export DASHBOARD_PASSWORD=$(openssl rand -hex 16)
echo "Generated Hermes Dashboard Password: ${DASHBOARD_PASSWORD}"

echo -n "${DASHBOARD_PASSWORD}" | gcloud secrets create hermes-dashboard-password \
  --data-file=- \
  --replication-policy="automatic"

gcloud secrets add-iam-policy-binding hermes-dashboard-password \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

5. Przygotowywanie zasobnika Cloud Storage i plików konfiguracyjnych

Hermes wymaga pamięci trwałej zamontowanej jako /opt/data. Użyjemy zasobnika Google Cloud Storage (GCS) i zamontujemy go za pomocą montowania woluminów Cloud Storage.

1. Tworzenie zasobnika Cloud Storage

gcloud storage buckets create gs://${BUCKET_NAME} --location=${REGION}

# Grant the service account permissions to mount the bucket
gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/storage.objectAdmin"

2. Utwórz ocenę config.yaml

Utwórz plik config.yaml. Pamiętaj, aby dodać znak _config_version: 12, aby konfiguracja została prawidłowo załadowana:

_config_version: 12

model:
  default: "google/gemini-3.8-flash"
  provider: "vertex"

dashboard:
  enabled: true

database:
  journal_mode: delete

3. Utwórz skrypt nadzorcy (run_hermes.py)

Cloud Storage nie obsługuje mechanizmów blokowania plików, których bazy danych SQLite potrzebują do bezpiecznego działania. Aby zapobiec uszkodzeniu bazy danych, potrzebujemy niestandardowego skryptu „nadzorcy” (run_hermes.py). Przed uruchomieniem agenta skrypt ten konfiguruje usługę Hermes tak, aby przechowywała tymczasowe blokady bazy danych w pamięci lokalnej kontenera, a nie w Cloud Storage.

Utwórz run_hermes.py lokalnie:

import os
import shutil
import subprocess
import sys
import threading
import time

print(
    "=== INITIALIZING HERMES SUPERVISOR ===", flush=True
)

# 1. Local Directory Setup
# Creates temporary, local folders (in /tmp) for the agent's caches and working directories.
# See more below in comment section NOTE ON CLOUD STORAGE FUSE
home_dir = "/tmp/hermes_home"
hermes_dir = os.path.join(home_dir, ".hermes")
os.makedirs(hermes_dir, exist_ok=True)
os.makedirs("/tmp/logs", exist_ok=True)
os.makedirs("/tmp/skills", exist_ok=True)
os.makedirs("/tmp/uv_cache", exist_ok=True)
os.makedirs("/tmp/cache", exist_ok=True)
os.makedirs("/opt/data/workspace", exist_ok=True)
os.makedirs("/opt/data/.hermes", exist_ok=True)

# 2. State Restoration & Database Config
# Copies your existing configurations and chat history (state.db) from Cloud Storage into the local folders. 
# It also forces the SQLite database into TRUNCATE mode, a crucial step to prevent database corruption 
# when eventually saving back to Cloud Storage. See more in section 3. Note on Cloud Storage Fuse below
if os.path.exists("/opt/data/config.yaml"):
  shutil.copy("/opt/data/config.yaml", os.path.join(hermes_dir, "config.yaml"))
  print(f"Synced config.yaml -> {hermes_dir}/config.yaml", flush=True)
elif os.path.exists("/opt/data/.hermes/config.yaml"):
  shutil.copy("/opt/data/.hermes/config.yaml", os.path.join(hermes_dir, "config.yaml"))
  print(f"Synced config.yaml from .hermes -> {hermes_dir}/config.yaml", flush=True)

if os.path.exists("/opt/data/.env"):
  shutil.copy("/opt/data/.env", os.path.join(hermes_dir, ".env"))
  print(f"Synced .env -> {hermes_dir}/.env", flush=True)
elif os.path.exists("/opt/data/.hermes/.env"):
  shutil.copy("/opt/data/.hermes/.env", os.path.join(hermes_dir, ".env"))
  print(f"Synced .env from .hermes -> {hermes_dir}/.env", flush=True)

if os.path.exists("/opt/data/.hermes/state.db"):
  shutil.copy("/opt/data/.hermes/state.db", os.path.join(hermes_dir, "state.db"))
  print(f"Synced state.db -> {hermes_dir}/state.db (restored previous chats!)", flush=True)

# 3. Note on Cloud Storage Fuse
# Cloud Storage FUSE is optimized for object storage, but is not fully POSIX compliant.
# This means GCS lacks the byte-range file locking required by active caches and default SQLite (WAL mode) 
# which SQLite depends on to prevent data collisions.
# Without these locks, SQLite experiences database corruption and blocked I/O operations.
# To ensure stability, we route these active I/O processes to local container memory (/tmp).
# See section 5 Enable Autosave below on how /tmp is uploaded to Cloud Storage.
# Read more: https://cloud.google.com/storage/docs/cloud-storage-fuse/overview#differences-and-limitations
db_path = os.path.join(hermes_dir, "state.db")
try:
  import sqlite3
  conn = sqlite3.connect(db_path)
  conn.execute("PRAGMA journal_mode=TRUNCATE;")
  conn.close()
  print("Configured SQLite database to TRUNCATE mode for direct single-file persistence", flush=True)
except Exception as e:
  print(f"Warning: Failed to configure TRUNCATE mode: {e}", flush=True)

subprocess.run(["chmod", "-R", "777", "/tmp"], check=False)

# 4. Update system environment variables
# Hermes needs to know to look at the new local /tmp folders rather than defaulting to the mounted bucket.
env = dict(os.environ)
env["HOME"] = home_dir
env["HERMES_HOME"] = hermes_dir
env["PATH"] = "/opt/hermes/.venv/bin:/opt/hermes/bin:" + env.get("PATH", "")
env["PYTHONUNBUFFERED"] = "1"
env["HERMES_STATE_PATH"] = hermes_dir
env["HERMES_SKILLS_PATH"] = "/tmp/skills"
env["UV_CACHE_DIR"] = "/tmp/uv_cache"
env["XDG_CACHE_HOME"] = "/tmp/cache"
env["SQLITE_BUSY_TIMEOUT"] = "30000"
env["HERMES_ALLOW_ROOT_GATEWAY"] = "1"
env["HERMES_WORKSPACE"] = "/opt/data/workspace"
env["HERMES_WRITE_SAFE_ROOT"] = "/opt/data"

python_bin = "/opt/hermes/.venv/bin/python3"

# 5. Enable Autosave 
# Spawn a background worker thread to watch your local database and config files every 5 seconds.
# As you chat with your agent, this worker thread automatically copies the updated database content
# back to Cloud Storage to persist it.
def sync_to_gcs_loop():
  files_to_sync = ["state.db", "config.yaml", ".env"]
  last_mtimes = {}
  
  # Initialize last_mtimes
  for f in files_to_sync:
    path = os.path.join(hermes_dir, f)
    if os.path.exists(path):
      last_mtimes[f] = os.path.getmtime(path)
    else:
      last_mtimes[f] = 0
      
  while True:
    time.sleep(5)
    for f in files_to_sync:
      src_path = os.path.join(hermes_dir, f)
      if os.path.exists(src_path):
        try:
          mtime = os.path.getmtime(src_path)
          if mtime > last_mtimes.get(f, 0):
            dst_path = os.path.join("/opt/data/.hermes", f)
            shutil.copy2(src_path, dst_path)
            last_mtimes[f] = mtime
            print(f"Auto-saved {f} to GCS volume mount", flush=True)
        except Exception as e:
          print(f"Error auto-saving {f} to GCS: {e}", flush=True)

threading.Thread(target=sync_to_gcs_loop, daemon=True).start()


# 6. Launch the Hermes Gateway (the AI backend) and the Web Dashboard (the UI)
# These are launched as parallel processes, sending logs to Cloud Run via stdout & stderr
print("=== STARTING GATEWAY IN BACKGROUND ===", flush=True)
gw = subprocess.Popen(
    [python_bin, "-m", "hermes_cli.main", "gateway", "run"],
    env=env,
    cwd="/opt/data/workspace",
    stdout=subprocess.PIPE,
    stderr=subprocess.STDOUT,
    text=True,
    bufsize=1,
)

def stream_gw():
  for line in iter(gw.stdout.readline, ""):
    if line:
      print(f"[GATEWAY] {line.rstrip()}", flush=True)

threading.Thread(target=stream_gw, daemon=True).start()

print("=== STARTING DASHBOARD ON 0.0.0.0:8080 ===", flush=True)
sys.stdout.flush()

dash = subprocess.Popen(
    [
        python_bin,
        "-m",
        "hermes_cli.main",
        "dashboard",
        "--host",
        "0.0.0.0",
        "--port",
        "8080",
        "--skip-build",
    ],
    env=env,
    cwd="/opt/data/workspace",
    stdout=subprocess.PIPE,
    stderr=subprocess.STDOUT,
    text=True,
    bufsize=1,
)

for line in iter(dash.stdout.readline, ""):
  if line:
    print(f"[DASHBOARD] {line.rstrip()}", flush=True)

rc = dash.wait()
print(f"DASHBOARD EXITED WITH RETURN CODE: {rc}", flush=True)

while True:
  time.sleep(10)

4. Tworzenie skryptu startowego (start_hermes.sh)

Utwórz start_hermes.sh lokalnie.

#!/bin/sh
set -e
export PYTHONUNBUFFERED=1
exec python3 /opt/data/run_hermes.py

5. Przesyłanie plików do Cloud Storage

Skopiuj pliki konfiguracyjne do katalogu głównego zasobnika GCS:

gcloud storage cp config.yaml run_hermes.py start_hermes.sh gs://${BUCKET_NAME}/

6. Wdrażanie usługi Hermes na instancjach Cloud Run

Do wdrożenia kontenera używamy gcloud beta run instances deploy. To polecenie zawiera konkretne konfiguracje, które pozwalają rozwiązać znane problemy z GCSFuse i limitami kontenerów.

Sprawdź, czy zmienne środowiskowe (PROJECT_ID, REGION, BUCKET_NAME, SERVICE_ACCOUNT) są eksportowane w aktywnej sesji terminala.

Wdróż instancję:

gcloud beta run instances deploy hermes-instance \
  --image nousresearch/hermes-agent:latest \
  --service-account ${SERVICE_ACCOUNT} \
  --command "/bin/sh" \
  --args "/opt/data/start_hermes.sh" \
  --port 8080 \
  --cpu 2 \
  --memory 4Gi \
  --ingress all \
  --no-invoker-iam-check \
  --add-volume name=hermes-storage,mount-path=/opt/data,type=cloud-storage,mount-options="uid=2000;gid=2000;file-mode=0777;dir-mode=0777;implicit-dirs",bucket=$BUCKET_NAME \
  --set-secrets "HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=hermes-dashboard-password:latest" \
  --set-env-vars "PYTHONUNBUFFERED=1,VERTEX_PROJECT_ID=$PROJECT_ID,VERTEX_LOCATION=global,HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin,HERMES_ALLOW_ROOT_GATEWAY=1,HERMES_WORKSPACE=/opt/data/workspace,HERMES_WRITE_SAFE_ROOT=/opt/data" \
  --region $REGION \
  --project $PROJECT_ID

Ważne konfiguracje uwzględnione powyżej:

• --service-account: dołącza dedykowane konto usługi hermes-sa.
• Skrypty nadzorcy: start_hermes.sh wywołuje niestandardowy skrypt nadzorcy w Pythonierun_hermes.py, który kieruje limity blokowania SQLite i problemy z pamięcią podręczną z GCS FUSE do lokalnego tmpfs.
• --set-secrets: wstrzykuje dane logowania bezpośrednio z usługi Secret Manager do zmiennych środowiskowych.

7. Bezpośrednie korzystanie z interfejsu internetowego Hermes

Po wdrożeniu możesz uzyskać dostęp do panelu pod wygenerowanym adresem URL .run.app. Gdy pojawi się prośba o uwierzytelnienie, wpisz admin jako nazwę użytkownika i ${DASHBOARD_PASSWORD} jako hasło.

Czat z agentem

Możesz na przykład echo "hello", aby sprawdzić, czy agent działa.

Testowanie pamięci trwałej

Możesz przetestować pamięć trwałą w zasobniku Google Cloud, zadając agentowi pytanie

Write "hello world" to a file named hello.txt in your workspace.

Następnie w powłoce możesz sprawdzić, czy plik został zapisany, uruchamiając

gcloud storage cat gs://$BUCKET_NAME/workspace/hello.txt

Na koniec, aby sprawdzić, czy czaty i pliki są zachowywane w nowych instancjach Cloud Run (instancja Cloud Run może działać nieprzerwanie przez maksymalnie 7 dni, a domyślnie skonfigurowana jest automatyczna zasada ponownego uruchamiania), możesz ponownie uruchomić polecenie gcloud beta run instances deploy w taki sam sposób jak wcześniej. Następnie zobaczysz sesje czatu. Możesz zapytać agenta:

Read the contents of the file hello.txt in your workspace.

i zobaczysz „hello world”.

8. Czyszczenie

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby zużyte w tym samouczku:

1. Usuń instancję Cloud Run:

   gcloud beta run instances delete hermes-instance --region ${REGION} --quiet
   

2. Usuwanie obiektów tajnych usługi Secret Manager:

   gcloud secrets delete hermes-dashboard-password --quiet
   

3. Usuwanie zasobnika Cloud Storage:

   gcloud storage rm -r gs://${BUCKET_NAME}
   

4. Usuwanie dedykowanego konta usługi:

   gcloud iam service-accounts delete ${SERVICE_ACCOUNT} --quiet
   

9. Podsumowanie

Gratulacje! Udało Ci się wdrożyć bezpieczną, w pełni trwałą instancję agenta Hermes w instancjach Cloud Run obsługiwanych przez Cloud Storage.

Czego się dowiedziałeś(-aś)

• Jak wdrożyć agenta Hermes na instancjach Cloud Run.
• Jak montować zasobniki Cloud Storage w instancjach Cloud Run za pomocą GCSFuse.
• Jak bezpiecznie skonfigurować SQLite i pamięci podręczne, aby ominąć ograniczenia blokowania plików GCSFuse.