Как развернуть агент Hermes на экземплярах Cloud Run

1. Введение

Обзор

В этой лабораторной работе вы развернете полностью постоянный, защищенный экземпляр агента Hermes (от Nous Research) в Cloud Run Instances . Вы будете взаимодействовать со своим ИИ-агентом с помощью веб-панели Hermes и создавать резервные копии его постоянного рабочего пространства в Google Cloud Storage .

Hermes поддерживает режим шлюза, который может работать как автоматически масштабируемая служба Cloud Run, а также выступает в качестве агента с сохранением состояния, сканирующего навыки при загрузке и обрабатывающего фоновые процессы. Экземпляры Cloud Run обеспечивают долговременную, индивидуально адресуемую среду, идеально подходящую для этой рабочей нагрузки.

Что вы будете делать

• Подготовьте сегмент Cloud Storage для сохранения состояния и конфигураций контейнера.
• Создайте собственный Python-супервизор ( run_hermes.py ) и скрипт запуска ( start_hermes.sh ) для инициализации при загрузке.
• Разверните агент Hermes, используя gcloud beta run instances deploy .
• Получите доступ к панели управления Hermes и пройдите аутентификацию.

Что вы узнаете

• Как развернуть агент Hermes на экземплярах Cloud Run.
• Как подключить хранилища Cloud Storage к экземплярам Cloud Run с помощью GCSFuse.
• Как безопасно настроить SQLite и временные кэши для обхода ограничений блокировки файлов GCSFuse.

2. Настройка и требования

Настройка проекта GCP

1. Войдите в консоль Google Cloud .
2. Создайте или выберите проект Google Cloud.
3. Убедитесь, что для вашего проекта в Google Cloud включена функция выставления счетов.

Открытая облачная оболочка

Активируйте Google Cloud Shell с верхней панели инструментов Cloud Console.

Настройте проект и установите бета-версию gcloud.

Сначала задайте свой проект и регион в качестве переменных среды.

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

И настройте свой проект для работы с gcloud.

gcloud config set project $PROJECT_ID

Убедитесь, что для gcloud beta run instances установлен компонент beta :

gcloud components install beta --quiet

И ваша версия gcloud обновлена.

gcloud components updates

Включите необходимые API Google Cloud.

В Cloud Shell включите API Cloud Run, Cloud Storage и Secret Manager:

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

3. Создайте выделенный сервисный аккаунт.

Чтобы соблюсти принцип минимальных привилегий, создайте для агента Hermes отдельную учетную запись службы IAM и предоставьте ей необходимые разрешения для вызова моделей искусственного интеллекта Vertex:

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. Сохраните учетные данные в Secret Manager.

Мы будем хранить конфиденциальные учетные данные, такие как пароль от панели управления, в Google Cloud Secret Manager, чтобы Cloud Run мог безопасно внедрять их в контейнер при загрузке.

Сгенерируйте надежный случайный пароль для своей панели управления и сохраните его в 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. Подготовка сегмента облачного хранилища и конфигурационных файлов.

Для работы Hermes требуется постоянное хранилище, смонтированное как /opt/data . Мы будем использовать корзину Google Cloud Storage (GCS) и смонтируем её с помощью монтирования томов Cloud Storage.

1. Создайте сегмент облачного хранилища.

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. Создайте config.yaml

Создайте файл config.yaml . Обязательно укажите _config_version: 12 , чтобы обеспечить корректную загрузку конфигурации:

_config_version: 12

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

dashboard:
  enabled: true

database:
  journal_mode: delete

3. Создайте скрипт супервизора ( run_hermes.py )

Облачное хранилище не поддерживает специфические механизмы блокировки файлов, необходимые для безопасной работы баз данных SQLite. Для предотвращения повреждения базы данных нам необходим пользовательский скрипт «супервизора» ( run_hermes.py ). Этот скрипт настраивает Hermes на хранение временных блокировок базы данных в локальной памяти контейнера, а не в облачном хранилище, перед запуском агента.

Создайте run_hermes.py локально:

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. Создайте скрипт запуска ( start_hermes.sh )

Создайте start_hermes.sh локально.

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

5. Загрузка файлов в облачное хранилище.

Скопируйте файлы конфигурации в корневую папку вашего хранилища GCS:

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

6. Разверните Hermes на экземплярах Cloud Run.

Для развертывания контейнера мы используем gcloud beta run instances deploy . Эта команда включает в себя специальные настройки для решения известных проблем с GCSFuse и ограничениями контейнеров.

Убедитесь, что ваши переменные среды ( PROJECT_ID , REGION , BUCKET_NAME , SERVICE_ACCOUNT ) экспортированы в активную сессию терминала.

Разверните экземпляр:

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

Важные настройки, указанные выше:

• --service-account : Подключает выделенную учетную запись службы hermes-sa .
• Скрипты супервизора : start_hermes.sh вызывает пользовательский скрипт супервизора на Python run_hermes.py , который перенаправляет ограничения на блокировки SQLite и проблемы с кэшированием из GCS FUSE в локальную файловую систему tmpfs.
• --set-secrets : Внедряет учетные данные непосредственно из Secret Manager в переменные среды.

7. Взаимодействуйте напрямую через веб-интерфейс Hermes.

После развертывания вы сможете получить доступ к своей панели управления по сгенерированному URL-адресу .run.app . При запросе аутентификации введите admin в качестве имени пользователя и ваш ${DASHBOARD_PASSWORD} в качестве пароля.

Пообщайтесь со своим агентом.

Вы можете попробовать использовать команду, например, echo "hello" чтобы убедиться в работоспособности агента.

Тестирование постоянного хранилища

Вы можете проверить работу постоянного хранилища в вашем Google Cloud Bucket, обратившись к агенту.

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

Затем в вашей командной оболочке вы можете проверить, был ли файл записан, выполнив команду...

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

Наконец, чтобы убедиться, что ваши чаты и файлы сохраняются при запуске новых экземпляров Cloud Run (поскольку экземпляр Cloud Run может работать непрерывно до 7 дней, а политика автоматического перезапуска настроена по умолчанию), вы можете повторно запустить команду gcloud beta run instances deploy точно так же, как и раньше. После этого вы увидите свои сеансы чата. И вы сможете обратиться к своему агенту.

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

И вы увидите "hello world".

8. Уборка

Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, использованные в этом практическом задании:

1. Удалите экземпляр Cloud Run :

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

2. Удалить секреты менеджера секретов :

   gcloud secrets delete hermes-dashboard-password --quiet
   

3. Удалить корзину облачного хранилища :

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

4. Удалить выделенный сервисный аккаунт :

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

9. Заключение

Поздравляем! Вы успешно развернули безопасный, полностью постоянный экземпляр Hermes Agent на Cloud Run Instances с использованием облачного хранилища!

Что вы узнали

• Как развернуть агент Hermes на экземплярах Cloud Run.
• Как подключить хранилища Cloud Storage к экземплярам Cloud Run с помощью GCSFuse.
• Как безопасно настроить SQLite и временные кэши для обхода ограничений блокировки файлов GCSFuse.