[Hermes] Hướng dẫn Cấu hình Managed Scope trong Hermes Agent

# Hướng dẫn Cấu hình Managed Scope trong Hermes Agent

Tài liệu tóm tắt và hướng dẫn thực hành chi tiết về cơ chế **Managed Scope** của Hermes Agent, trích xuất từ tài liệu chính thức: [Hermes Agent - Managed Scope]( Managed Scope | Hermes Agent ).

-–

## 1. Tổng quan về Managed Scope (Overview)

### Managed Scope là gì?

**Managed Scope** là cơ chế cho phép **Quản trị viên hệ thống (Administrator / IT)** thiết lập và áp đặt một tập hợp cấu hình (`config.yaml`) và biến môi trường/secrets (`.env`) ở cấp độ hệ thống. Các giá trị này:

- **Bất biến đối với người dùng thông thường (User-immutable):** Người dùng thông thường (non-root) không thể ghi đè hoặc sửa đổi các khóa đã bị ghim.

- **Áp dụng cho toàn hệ thống:** Tất cả người dùng và tiến trình Hermes chạy trên máy sẽ tuân theo các chính sách này.

### Mục đích & Trường hợp sử dụng

- **Triển khai cấp tổ chức / Doanh nghiệp (Fleet/Org Deployments):** Đảm bảo tính đồng nhất trên hàng loạt máy trạm hoặc máy chủ.

- **Ép buộc chính sách bảo mật & endpoint:**

  • Ghim nhà cung cấp mô hình AI (`model.provider`).

  • Cố định địa chỉ API Gateway nội bộ (`OPENAI_API_BASE`).

  • Bắt buộc kích hoạt chế độ ẩn secrets (`security.redact_secrets: true`).

- **Phân tách quyền hạn thông minh (Leaf-level Merging):** Chỉ những khóa (keys) được Admin định nghĩa trong Managed Scope mới bị khóa cố định; các khóa còn lại người dùng vẫn toàn quyền cấu hình trong `~/.hermes/config.yaml` và `~/.hermes/.env`.

-–

## 2. Vị trí lưu trữ & Phân quyền tệp (File Structure & Permissions)

Mặc định trên hệ thống Linux/POSIX, Managed Scope được lưu tại thư mục `/etc/hermes/`:

```text

/etc/hermes/

├── config.yaml # Tầng cấu hình quản trị (Ưu tiên cao hơn ~/.hermes/config.yaml)

└── .env # Tầng biến môi trường quản trị (Ưu tiên cao hơn ~/.hermes/.env & Shell env)

```

### Cơ chế thực thi (Enforcement Mechanism)

Cơ chế bảo vệ dựa vào **phân quyền hệ thống tệp POSIX**:

- **Owner:** Thuộc sở hữu của `root`.

- **Thư mục:** Quyền `0755` (`drwxr-xr-x`) — Mọi user có thể đọc/truy cập, chỉ root mới có thể tạo/sửa/xóa.

- **Tệp tin:** Quyền `0644` (`-rw-r–r–`) — Mọi user có thể đọc, chỉ root mới có thể ghi.

> **Lưu ý:** Cả hai file `config.yaml` và `.env` đều là tùy chọn. Nếu không có thư mục `/etc/hermes/`, Hermes sẽ hoạt động bình thường theo cấu hình cấp người dùng.

### Tùy chỉnh đường dẫn Managed Scope (`HERMES_MANAGED_DIR`)

Trong môi trường container (Docker) hoặc khi muốn đặt thư mục chính sách ở vị trí khác:

```bash

export HERMES_MANAGED_DIR=/opt/org/hermes-policy

```

*(Biến môi trường này cần được cố định bởi Admin trong Dockerfile hoặc service unit, tránh để user tùy tiện thay đổi nhằm bypass chính sách).*

-–

## 3. Thứ tự ưu tiên (Precedence Order)

Đối với các khóa (keys) được định nghĩa trong Managed Scope, thứ tự ưu tiên giải quyết cấu hình như sau:

| Thứ tự | Nguồn cấu hình | Mô tả |

| :— | :— | :— |

| **1 (Cao nhất)** | `/etc/hermes/config.yaml` | Cấu hình cấp hệ thống do Admin quản lý |

| **2** | `/etc/hermes/.env` | Biến môi trường cấp hệ thống do Admin quản lý |

| **3** | Shell Environment Variables | Biến môi trường export trong terminal *(Bị Managed Scope ghi đè nếu trùng key)* |

| **4** | `~/.hermes/config.yaml` | Cấu hình cấp người dùng |

| **5 (Thấp nhất)** | `~/.hermes/.env` | Biến môi trường cấp người dùng |

### Nguyên lý gộp cấu hình cấp lá (Leaf-level Merging)

- Việc ghim `model.default` **không** khóa toàn bộ nhóm `model.*`.

- Ví dụ, nếu file `/etc/hermes/config.yaml` chứa:

```yaml

model:

default: org/standard-model

```

Thì chỉ `model.default` bị cố định; người dùng vẫn có thể tự do cấu hình `model.fallback`, `model.temperature`… trong `~/.hermes/config.yaml`.

-–

## 4. Hướng dẫn thiết lập cho Quản trị viên (Admin Setup Guide)

### Bước 1: Tạo thư mục cấu hình hệ thống

```bash

sudo mkdir -p /etc/hermes

```

### Bước 2: Tạo tệp cấu hình `config.yaml`

Ghim các giá trị cấu hình mặc định hoặc các quy tắc bảo mật bắt buộc:

```bash

sudo tee /etc/hermes/config.yaml > /dev/null <<‘YAML’

model:

provider: nous

security:

redact_secrets: true

YAML

```

### Bước 3: (Tùy chọn) Tạo tệp môi trường `.env`

Ghim các thông số môi trường dùng chung (không chứa secrets tối mật cá nhân):

```bash

sudo tee /etc/hermes/.env > /dev/null <<‘ENV’

OPENAI_API_BASE=https://inference.example.com/v1

ENV

```

### Bước 4: Thiết lập quyền truy cập bảo mật

```bash

sudo chmod 0755 /etc/hermes

sudo chmod 0644 /etc/hermes/config.yaml /etc/hermes/.env

```

Cấu hình sẽ tự động có hiệu lực ở lần khởi chạy Hermes tiếp theo.

-–

## 5. Kiểm tra & Giám sát Managed Scope

### 1. Kiểm tra qua Hermes CLI

```bash

# Xem danh sách cấu hình và các key bị ghim (kèm nguồn quản lý)

hermes config

# Báo cáo đường dẫn Managed Dir và số lượng key đã ghim

hermes doctor

```

### 2. Hành vi khi người dùng cố tình thay đổi cấu hình bị ghim

Khi người dùng chạy lệnh sửa đổi key đã được quản lý:

```bash

$ hermes config set model.default my/custom-model

```

**Kết quả phản hồi:**

```text

Cannot set ‘model.default’: it is managed by your administrator (/etc/hermes/config.yaml) and cannot be changed.

```

-–

## 6. Mô hình bảo mật & Giới hạn phiên bản v1 (Security & Limitations)

1. **Phụ thuộc vào quyền POSIX:** Nếu người dùng có quyền `sudo`/`root` hoặc quyền ghi vào `/etc/hermes`, họ có thể can thiệp hoặc vô hiệu hóa Managed Scope.

2. **Quyền đọc của tệp `.env` (`0644`):** File `.env` trong `/etc/hermes/` có quyền đọc công khai cho mọi user cục bộ. Do đó, chỉ dùng file này cho các cấu hình dùng chung (như Base URL, default flags), **không lưu token/secret có độ nhạy cảm cao**.

3. **Phạm vi của tiến trình con (Subprocess):** Managed Scope bảo vệ cấu hình Hermes ở cấp người dùng, nhưng không phải là sandbox tuyệt đối ngăn cản tiến trình con đổi biến môi trường trong shell riêng của agent.

4. **Các tính năng chưa hỗ trợ trong v1 (Dự kiến trong tương lai):**

  • Registry/Policy native riêng cho Windows / macOS.

  • Thư mục cấu hình phân tầng dạng `managed.d/`.

  • Cơ chế ký số và kiểm tra toàn vẹn (Signed / Integrity check).

  • Quản trị thiết bị tập trung từ xa (MDM).