Thiết lập Nix & NixOS

Đại lý Hermes vận chuyển một mảnh Nix với ba cấp độ tích hợp:

Cấp độ	Nó dành cho ai	Những gì bạn nhận được
**
`nix run
` /
`nix profile install

** | Bất kỳ người dùng Nix nào (macOS, Linux) | Tệp nhị phân dựng sẵn với tất cả các chi tiết — sau đó sử dụng quy trình làm việc CLI tiêu chuẩn | | Mô-đun NixOS (bản địa) | Triển khai máy chủ NixOS | Cấu hình khai báo, dịch vụ systemd cứng cáp, bí mật được quản lý | | Mô-đun NixOS (vùng chứa) | Đại lý cần tự sửa đổi | Mọi thứ ở trên, cộng với một bộ chứa Ubuntu ổn định nơi tác nhân có thể `apt

/ `pip

/ npm install |

What's different from the standard install

Trình cài đặt curl | bash tự quản lý Python, Node và các phần phụ thuộc. Flake Nix thay thế tất cả những thứ đó — mọi phần phụ thuộc Python đều là dẫn xuất Nix được xây dựng bởi uv2nix và các công cụ thời gian chạy (Node.js, git, ripgrep, ffmpeg) được gói vào PATH của tệp nhị phân. Không có pip thời gian chạy, không kích hoạt venv, không có `npm install

.

Đối với người dùng không sử dụng NixOS, điều này chỉ thay đổi bước cài đặt. Mọi thứ sau ( `Hermes setup

, `Hermes gateway install

, chỉnh sửa cấu hình) hoạt động giống hệt với cài đặt tiêu chuẩn.

Đối với người dùng mô-đun NixOS, toàn bộ vòng đời sẽ khác: cấu hình tồn tại trong `configuration.nix

, các bí mật đi qua sops-nix/agenix, dịch vụ là đơn vị systemd và các lệnh cấu hình CLI bị chặn. Bạn quản lý Hermes giống như cách bạn quản lý bất kỳ dịch vụ NixOS nào khác.

Điều kiện tiên quyết

• Nix đã bật vảy — Khuyến nghị Determinate Nix (bật vảy theo mặc định)
• Khóa API cho các dịch vụ bạn muốn sử dụng (tối thiểu: khóa OpenRouter hoặc Anthropic)

---

Bắt đầu nhanh (Bất kỳ người dùng Nix nào)

Không cần bản sao. Nix tìm nạp, xây dựng và chạy mọi thứ:

# Run directly (builds on first use, cached after)
nix run GitHub:NousResearch/Hermes-agent -- setup
nix run GitHub:NousResearch/Hermes-agent -- chat

# Or install persistently
nix profile install GitHub:NousResearch/Hermes-agent
Hermes setup
Hermes chat

`
``Sau 
`nix profile install

, 
`Hermes

, 
`Hermes-agent
` và 
`Hermes-ACP
` đều có trên PATH của bạn. Từ đây, quy trình làm việc giống hệt với [standard installation](./installation.md) - 
`Hermes setup
` hướng dẫn bạn lựa chọn nhà cung cấp, 
`Hermes gateway install
` thiết lập dịch vụ người dùng launchd (macOS) hoặc systemd và cấu hình tồn tại trong 

~/.Hermes/

.`<details
<summary<strongXây dựng từ bản sao cục bộ</strong</summary

``` bash
git clone https://GitHub.com/NousResearch/Hermes-agent.git
cd Hermes-agent
nix build
./result/bin/Hermes setup

`
``</details

---

## Mô-đun NixOS

Flack xuất 
`NixOSModules.default

 - một mô-đun dịch vụ NixOS đầy đủ quản lý khai báo việc tạo, thư mục, tạo cấu hình, bí mật, tài liệu và vòng đời dịch vụ.

:::note
Mô-đun này yêu cầu NixOS. Đối với các hệ thống không phải NixOS (macOS, các bản phân phối Linux khác), hãy sử dụng 
`nix profile install
` và quy trình làm việc CLI tiêu chuẩn ở trên.

:::

### Thêm đầu vào Flake

`nix
# /etc/NixOS/flake.nix (or your system flake)
{
  inputs = {
    nixpkgs.url = "GitHub:NixOS/nixpkgs/NixOS-unstable";
    Hermes-agent.url = "GitHub:NousResearch/Hermes-agent";
  };`outputs = { nixpkgs, Hermes-agent, ... }: {
    NixOSConfigurations.your-host = nixpkgs.lib.NixOSSystem {
      system = "x86_64-Linux";
      modules = [
        Hermes-agent.NixOSModules.default
        ./configuration.nix
      ];
    };
  };
}

`

### Cấu hình tối thiểu

`nix
# configuration.nix
{ config, ... }: {
  services.Hermes-agent = {
    enable = true;
    settings.model.default = "Anthropic/Claude-sonnet-4";
    environmentFiles = [ config.sops.secrets."Hermes-env".path ];
    addToSystemPackages = true;
  };
}

`
``Thế thôi. 
`NixOS-rebuild switch
` tạo người dùng 
`Hermes

, tạo 
`config.yaml

, kết nối bí mật và khởi động cổng — một dịch vụ chạy dài kết nối tác nhân với các nền tảng nhắn tin (Telegram, Discord, v.v.) và lắng nghe tin nhắn đến.

:::warning[Secrets are required]
Dòng 
`environmentFiles
` ở trên giả sử bạn đã định cấu hình [sops-nix](https://GitHub.com/Mic92/sops-nix) hoặc [agenix](https://GitHub.com/ryantm/agenix). Tệp phải chứa ít nhất một khóa nhà cung cấp LLM (ví dụ: 
`OpenRouter_API_KEY=sk-or-...

). Xem [Secrets Management](#secrets-management) để biết thiết lập đầy đủ. Nếu chưa có trình quản lý bí mật, bạn có thể sử dụng một tệp đơn giản làm điểm bắt đầu — chỉ cần đảm bảo rằng nó không thể đọc được trên thế giới:

``` bash
echo "OpenRouter_API_KEY=sk-or-your-key" | sudo install -m 0600 -o Hermes /dev/stdin /var/lib/Hermes/env

`

`
`nix
services.Hermes-agent.environmentFiles = [ "/var/lib/Hermes/env" ];

`

`
:::

:::tip[addToSystemPackages]
Việc đặt 
`addToSystemPackages = true
` thực hiện hai việc: đặt 
`Hermes
` CLI trên hệ thống của bạn PATH **và** đặt 
`Hermes_HOME
` trên toàn hệ thống để CLI tương tác chia sẻ trạng thái (phiên, kỹ năng, cron) với dịch vụ cổng. Nếu không có nó, việc chạy 
`Hermes
` trong shell của bạn sẽ tạo ra một thư mục 

~/.Hermes/
` riêng.
:::

### CLI nhận biết vùng chứa

:::info
Khi 
`container.enable = true
` và 
`addToSystemPackages = true

, **mọi** lệnh 
`Hermes
` trên máy chủ sẽ tự động định tuyến vào vùng chứa được quản lý. Điều này có nghĩa là phiên CLI tương tác của bạn chạy trong cùng môi trường với dịch vụ cổng — với quyền truy cập vào tất cả các gói và công cụ được cài đặt trong vùng chứa.- Định tuyến minh bạch: 
`Hermes chat

, 
`Hermes sessions list

, 
`Hermes version

, v.v. tất cả đều thực thi vào container dưới mui xe
- Tất cả các cờ CLI đều được chuyển tiếp nguyên trạng
- Nếu vùng chứa không chạy, CLI sẽ thử lại trong thời gian ngắn (5 giây với vòng quay để sử dụng tương tác, 10 giây im lặng đối với tập lệnh) rồi thất bại với một lỗi rõ ràng — không có dự phòng im lặng
- Đối với các nhà phát triển làm việc trên cơ sở mã Hermes, hãy đặt 
`Hermes_DEV=1
` để bỏ qua định tuyến vùng chứa và trực tiếp chạy thanh toán cục bộ

Đặt 
`container.hostUsers
` để tạo liên kết tượng trưng 

~/.Hermes
` tới thư mục trạng thái dịch vụ, do đó CLI máy chủ và các phiên, cấu hình và bộ nhớ chia sẻ vùng chứa:

`nix
services.Hermes-agent = {
  container.enable = true;
  container.hostUsers = [ "your-username" ];
  addToSystemPackages = true;
};

`
``Người dùng được liệt kê trong 
`hostUsers
` sẽ tự động được thêm vào nhóm 
`Hermes
` để truy cập quyền truy cập tệp.

**Người dùng Podman:** Dịch vụ NixOS chạy vùng chứa dưới dạng root. Người dùng Docker có quyền truy cập thông qua ổ cắm nhóm 
`Docker

, nhưng các vùng chứa gốc của Podman yêu cầu sudo. Cấp sudo không cần mật khẩu cho thời gian chạy vùng chứa của bạn:

`nix
security.sudo.extraRules = [{
  users = [ "your-username" ];
  commands = [{
    command = "/run/current-system/sw/bin/podman";
    options = [ "NOPASSWD" ];
  }];
}];

`
``CLI tự động phát hiện khi cần sudo và sử dụng nó một cách minh bạch. Nếu không có điều này, bạn sẽ cần chạy 
`sudo Hermes chat
` theo cách thủ công.
:::

### Xác minh nó hoạt động

Sau 
`NixOS-rebuild switch

, hãy kiểm tra xem dịch vụ có đang chạy không:

``` bash

# Check service status
systemctl status Hermes-agent

# Watch logs (Ctrl+C to stop)
journalctl -u Hermes-agent -f

# If addToSystemPackages is true, test the CLI
Hermes version
Hermes config       # shows the generated config

`

### Chọn Chế độ Triển khai

Mô-đun hỗ trợ hai chế độ, được điều khiển bởi 
`container.enable

:

| | **Gốc** (mặc định) | **Bình chứa** |
|---|---|---|
| Nó chạy như thế nào | Dịch vụ systemd cứng trên máy chủ | Bộ chứa Ubuntu liên tục được gắn liên kết 

/nix/store
` |
| An ninh |

NoNewPrivileges

, 
`ProtectSystem=strict

, 
`PrivateTmp
` | Cách ly vùng chứa, chạy với tư cách người dùng không có đặc quyền bên trong |
| Agent có thể tự cài đặt gói | Không - chỉ các công cụ trên PATH do Nix cung cấp | Có — Các lượt cài đặt 
`apt

, 
`pip

, 
`npm
` vẫn tồn tại sau mỗi lần khởi động lại |
| Bề mặt cấu hình | Tương tự | Tương tự |
| Khi nào nên chọn | Triển khai tiêu chuẩn, bảo mật tối đa, khả năng tái tạo | Tác nhân cần cài đặt gói thời gian chạy, môi trường có thể thay đổi, công cụ thử nghiệm |

Để bật chế độ vùng chứa, hãy thêm một dòng:

`nix
{
  services.Hermes-agent = {
    enable = true;
    container.enable = true;
    # ... rest of config is identical
  };
}

`

:::info
Chế độ vùng chứa tự động kích hoạt 
`virtualisation.Docker.enable
` thông qua 
`mkDefault

. Nếu bạn sử dụng Podman thay thế, hãy đặt 
`container.backend = "podman"
` và 
`virtualisation.Docker.enable = false

.
:::

---

## Cấu hình

### Cài đặt khai báo

Tùy chọn 
`settings
` chấp nhận tập hợp tùy ý được hiển thị dưới dạng 
`config.yaml

. Nó hỗ trợ hợp nhất sâu trên nhiều định nghĩa mô-đun (thông qua 
`lib.recursiveUpdate

), do đó bạn có thể chia cấu hình trên các tệp:

`nix
# base.nix
services.Hermes-agent.settings = {
  model.default = "Anthropic/Claude-sonnet-4";
  toolsets = [ "all" ];
  terminal = { backend = "local"; timeout = 180; };
};

# personality.nix
services.Hermes-agent.settings = {
  display = { compact = false; personality = "kawaii"; };
  memory = { memory_enabled = true; user_profile_enabled = true; };
};

`
``Cả hai đều được hợp nhất sâu tại thời điểm đánh giá. Các khóa do Nix khai báo luôn giành được các khóa trong 
`config.yaml
` hiện có trên đĩa, nhưng **các khóa do người dùng thêm mà Nix không chạm vào vẫn được giữ nguyên**. Điều này có nghĩa là nếu tác nhân hoặc chỉnh sửa thủ công thêm các khóa như 
`skills.disabled
` hoặc 
`streaming.enabled

, chúng vẫn tồn tại 
`NixOS-rebuild switch

.

:::note[Model naming]
`settings.model.default
` sử dụng mã nhận dạng mẫu mà nhà cung cấp của bạn mong đợi. Với [OpenRouter](https://OpenRouter.ai) (mặc định), chúng trông giống như 

"Anthropic/Claude-sonnet-4"
` hoặc 

"Google/Gemini-3-flash"

. Nếu bạn đang sử dụng trực tiếp một nhà cung cấp (Anthropic, OpenAI), hãy đặt 
`settings.model.base_url
` để trỏ đến API của họ và sử dụng ID mô hình gốc của họ (ví dụ: 

"Claude-sonnet-4-20250514"

). Khi không đặt 
`base_url

, Hermes mặc định là OpenRouter.
:::

:::tip[Discovering available config keys]
Chạy 
`nix build .#configKeys && cat result
` để xem mọi khóa cấu hình lá được trích xuất từ 
`DEFAULT_CONFIG
` của Python. Bạn có thể dán 
`config.yaml
` hiện có của mình vào tập hợp 
`settings
` — bản đồ cấu trúc 1:1.
:::

<details>
<summary><strong>Ví dụ đầy đủ: tất cả các cài đặt được tùy chỉnh phổ biến</strong></summary>

`nix
{ config, ... }: {
  services.Hermes-agent = {
    enable = true;
    container.enable = true;

# ── Model ──────────────────────────────────────────────────────────
    settings = {
      model = {
        base_url = "https://OpenRouter.ai/API/v1";
        default = "Anthropic/Claude-opus-4.6";
      };
      toolsets = [ "all" ];
      max_turns = 100;
      terminal = { backend = "local"; cwd = "."; timeout = 180; };
      compression = {
        enabled = true;
        threshold = 0.85;
        summary_model = "Google/Gemini-3-flash-preview";
      };
      memory = { memory_enabled = true; user_profile_enabled = true; };
      display = { compact = false; personality = "kawaii"; };
      agent = { max_turns = 60; verbose = false; };
    };

# ── Secrets ────────────────────────────────────────────────────────
    environmentFiles = [ config.sops.secrets."Hermes-env".path ];

# ── Documents ──────────────────────────────────────────────────────
    documents = {
      "USER.md" = ./documents/USER.md;
    };

# ── MCP Servers ────────────────────────────────────────────────────
    MCPServers.filesystem = {
      command = "npx";
      args = [ "-y" "@modelcontextprotocol/server-filesystem" "/data/workspace" ];
    };

# ── Container options ──────────────────────────────────────────────
    container = {
      image = "ubuntu:24.04";
      backend = "Docker";
      hostUsers = [ "your-username" ];
      extraVolumes = [ "/home/user/projects:/projects:rw" ];
      extraOptions = [ "--gpus" "all" ];
    };

# ── Service tuning ─────────────────────────────────────────────────
    addToSystemPackages = true;
    extraArgs = [ "--verbose" ];
    restart = "always";
    restartSec = 5;
  };
}

`
``</details>

### Escape Hatch: Mang theo cấu hình của riêng bạn

Nếu bạn muốn quản lý hoàn toàn 
`config.yaml
` bên ngoài Nix, hãy sử dụng 
`configFile

:

`nix
services.Hermes-agent.configFile = /etc/Hermes/config.yaml;

`
``Điều này bỏ qua hoàn toàn 
`settings

 - không hợp nhất, không tạo. Tệp được sao chép nguyên trạng sang 

$Hermes_HOME/config.yaml
` mỗi lần kích hoạt.

### Bảng tính tùy chỉnh

Tham khảo nhanh về những điều phổ biến nhất mà người dùng Nix muốn tùy chỉnh:| Tôi muốn... | Tùy chọn | Ví dụ |
|---|---|---|
| Thay đổi mô hình LLM |

settings.model.default
` | 

"Anthropic/Claude-sonnet-4"
` |
| Sử dụng điểm cuối của nhà cung cấp khác |

settings.model.base_url
` | 

"https://OpenRouter.ai/API/v1"
` |
| Thêm khóa API |

environmentFiles
` | 

[ config.sops.secrets."Hermes-env".path ]
` |
| Tạo cá tính cho đại lý |

$\{services.Hermes-agent.stateDir}/.Hermes/SOUL.md
` | quản lý tập tin trực tiếp |
| Thêm máy chủ công cụ MCP |

MCPServers.&lt;name>
` | Xem [MCP Servers](#MCP-servers) |
| Gắn thư mục máy chủ vào vùng chứa |

container.extraVolumes
` | 

[ "/data:/data:rw" ]
` |
| Truyền quyền truy cập GPU vào vùng chứa |

container.extraOptions
` | 

[ "--gpus" "all" ]
` |
| Sử dụng Podman thay vì Docker |

container.backend
` | 

"podman"
` |
| Chia sẻ trạng thái giữa máy chủ CLI và vùng chứa |

container.hostUsers
` | 

[ "sidbin" ]
` |
| Cung cấp thêm các công cụ cho đại lý |

extraPackages
` | 

[ pkgs.pandoc pkgs.imagemagick ]
` |
| Sử dụng hình ảnh cơ sở tùy chỉnh |

container.image
` | 

"ubuntu:24.04"
` |
| Ghi đè gói Hermes |

package
` | 
`inputs.Hermes-agent.packages.$\{system}.default.override { ... }
` |
| Thay đổi thư mục trạng thái |

stateDir
` | 

"/opt/Hermes"
` |
| Đặt thư mục làm việc của đại lý |

workingDirectory
` | 

"/home/user/projects"
` |

---

## Quản lý bí mật

:::danger[Never put API keys in XPROTECTX143XPROTECTX or XPROTECTX144XPROTECTX]
Các giá trị trong biểu thức Nix kết thúc bằng 

/nix/store

, có thể đọc được trên thế giới. Luôn sử dụng 
`environmentFiles
` với trình quản lý bí mật.
:::

Cả 
`environment
` (vars không bí mật) và 
`environmentFiles
` (tệp bí mật) đều được hợp nhất thành 

$Hermes_HOME/.env
` tại thời điểm kích hoạt (
`NixOS-rebuild switch

). Hermes đọc tệp này mỗi lần khởi động, vì vậy các thay đổi sẽ có hiệu lực với 
`systemctl restart Hermes-agent
` — không cần giải trí vùng chứa.

### sops-nix

`nix
{
  sops = {
    defaultSopsFile = ./secrets/Hermes.YAML;
    age.keyFile = "/home/user/.config/sops/age/keys.txt";
    secrets."Hermes-env" = { format = "YAML"; };
  };`services.Hermes-agent.environmentFiles = [
    config.sops.secrets."Hermes-env".path
  ];
}

`
``Tệp bí mật chứa các cặp khóa-giá trị:

``` yaml

# secrets/Hermes.YAML (encrypted with sops)
Hermes-env: |
    OpenRouter_API_KEY=sk-or-...
    Telegram_BOT_TOKEN=123456:ABC...
    Anthropic_API_KEY=sk-ant-...

`
``###agenix

`nix
{
  age.secrets.Hermes-env.file = ./secrets/Hermes-env.age;`services.Hermes-agent.environmentFiles = [
    config.age.secrets.Hermes-env.path
  ];
}

`

### OAuth / Auth Seeding

Đối với các nền tảng yêu cầu OAuth (ví dụ: Discord), hãy sử dụng 
`authFile
` để tạo thông tin xác thực trong lần triển khai đầu tiên:

`nix
{
  services.Hermes-agent = {
    authFile = config.sops.secrets."Hermes/auth.JSON".path;
    # authFileForceOverwrite = true;  # overwrite on every activation
  };
}

`
``Tệp chỉ được sao chép nếu 
`auth.JSON
` chưa tồn tại (trừ khi 
`authFileForceOverwrite = true

). Việc làm mới mã thông báo OAuth trong thời gian chạy được ghi vào thư mục trạng thái và được giữ nguyên trong quá trình xây dựng lại.

---

## Tài liệu

Tùy chọn 
`documents
` cài đặt các tệp vào thư mục làm việc của tác nhân (
`workingDirectory

, mà tác nhân đọc là không gian làm việc của nó). Hermes tìm kiếm tên tập tin cụ thể theo quy ước:
- **
`USER.md

** — bối cảnh về người dùng mà tác nhân đang tương tác.
- Bất kỳ tệp nào khác bạn đặt ở đây đều hiển thị với tác nhân dưới dạng tệp không gian làm việc.

Tệp nhận dạng tác nhân riêng biệt: Hermes tải 
`SOUL.md
` chính của nó từ 

$Hermes_HOME/SOUL.md

, trong mô-đun NixOS là 

$\{services.Hermes-agent.stateDir}/.Hermes/SOUL.md

. Việc đưa 
`SOUL.md
` vào 
`documents
` chỉ tạo tệp không gian làm việc và sẽ không thay thế tệp cá nhân chính.

`nix
{
  services.Hermes-agent.documents = {
    "USER.md" = ./documents/USER.md;  # path reference, copied from Nix store
  };
}

`
``Giá trị có thể là chuỗi nội tuyến hoặc tham chiếu đường dẫn. Các tệp được cài đặt trên mọi 
`NixOS-rebuild switch

.

---

## Máy chủ MCP

Tùy chọn 
`MCPServers
` khai báo cấu hình máy chủ [MCP (Model Context Protocol)](https://modelcontextprotocol.io). Mỗi máy chủ sử dụng truyền tải **stdio** (lệnh cục bộ) hoặc **HTTP** (URL từ xa).

### Stdio Transport (Máy chủ cục bộ)

`nix
{
  services.Hermes-agent.MCPServers = {
    filesystem = {
      command = "npx";
      args = [ "-y" "@modelcontextprotocol/server-filesystem" "/data/workspace" ];
    };
    GitHub = {
      command = "npx";
      args = [ "-y" "@modelcontextprotocol/server-GitHub" ];
      env.GitHub_PERSONAL_ACCESS_TOKEN = "\$\{GitHub_TOKEN}"; # resolved from .env
    };
  };
}

`

:::tip
Các biến môi trường trong giá trị 
`env
` được giải quyết từ 

$Hermes_HOME/.env
` khi chạy. Sử dụng 
`environmentFiles
` để đưa vào các bí mật — không bao giờ đặt mã thông báo trực tiếp vào cấu hình Nix.
:::

### Truyền tải HTTP (Máy chủ từ xa)

`nix
{
  services.Hermes-agent.MCPServers.remote-API = {
    url = "https://MCP.example.com/v1/MCP";
    headers.Authorization = "Bearer \$\{MCP_REMOTE_API_KEY}";
    timeout = 180;
  };
}

`

### Truyền tải HTTP với OAuth

Đặt 
`auth = "OAuth"
` cho máy chủ sử dụng OAuth 2.1. Hermes triển khai toàn bộ luồng PKCE — khám phá siêu dữ liệu, đăng ký khách hàng động, trao đổi mã thông báo và làm mới tự động.

`nix
{
  services.Hermes-agent.MCPServers.my-OAuth-server = {
    url = "https://MCP.example.com/MCP";
    auth = "OAuth";
  };
}

`
``Mã thông báo được lưu trữ trong 

$Hermes_HOME/MCP-tokens/&lt;server-name>.JSON
` và tồn tại trong suốt quá trình khởi động lại và xây dựng lại.

<details>
<summary><strong>Ủy quyền OAuth ban đầu trên máy chủ không đầu</strong></summary>

Ủy quyền OAuth đầu tiên yêu cầu luồng chấp thuận dựa trên trình duyệt. Trong triển khai không có đầu, Hermes in URL ủy quyền tới thiết bị xuất chuẩn/nhật ký thay vì mở trình duyệt.

**Tùy chọn A: Khởi động tương tác** — chạy luồng một lần qua 
`Docker exec
` (vùng chứa) hoặc 
`sudo -u Hermes
` (gốc):

``` bash

# Container mode
Docker exec -it Hermes-agent \
  Hermes MCP add my-OAuth-server --url https://MCP.example.com/MCP --auth OAuth

# Native mode
sudo -u Hermes Hermes_HOME=/var/lib/Hermes/.Hermes \
  Hermes MCP add my-OAuth-server --url https://MCP.example.com/MCP --auth OAuth

`
``Vùng chứa sử dụng 

--network=host

, do đó, trình nghe gọi lại OAuth trên 
`127.0.0.1
` có thể truy cập được từ trình duyệt máy chủ.**Tùy chọn B: Chuẩn bị sẵn mã thông báo** — hoàn thành quy trình trên máy trạm, sau đó sao chép mã thông báo:

``` bash
Hermes MCP add my-OAuth-server --url https://MCP.example.com/MCP --auth OAuth
scp ~/.Hermes/MCP-tokens/my-OAuth-server\{,.CLIent}.JSON \
    server:/var/lib/Hermes/.Hermes/MCP-tokens/

# Ensure: chown Hermes:Hermes, chmod 0600

`
``</details>

### Lấy mẫu (Yêu cầu LLM do máy chủ khởi tạo)

Một số máy chủ MCP có thể yêu cầu hoàn thành LLM từ tác nhân:

`nix
{
  services.Hermes-agent.MCPServers.analysis = {
    command = "npx";
    args = [ "-y" "analysis-server" ];
    sampling = {
      enabled = true;
      model = "Google/Gemini-3-flash";
      max_tokens_cap = 4096;
      timeout = 30;
      max_rpm = 10;
    };
  };
}

`

---

## Chế độ quản lý

Khi Hermes chạy qua mô-đun NixOS, các lệnh CLI sau sẽ bị **chặn** kèm theo lỗi mô tả hướng bạn đến 
`configuration.nix

:

| Lệnh bị chặn | Tại sao |
|---|---|
| 
`Hermes setup
` | Cấu hình mang tính khai báo - chỉnh sửa 
`settings
` trong cấu hình Nix của bạn |
| 
`Hermes config edit
` | Cấu hình được tạo từ 
`settings
` |
| 
`Hermes config set &lt;key> &lt;value>
` | Cấu hình được tạo từ 
`settings
` |
| 
`Hermes gateway install
` | Dịch vụ systemd được quản lý bởi NixOS |
| 
`Hermes gateway uninstall
` | Dịch vụ systemd được quản lý bởi NixOS |

Điều này ngăn cản sự trôi dạt giữa những gì Nix khai báo và những gì có trên đĩa. Phát hiện sử dụng hai tín hiệu:
1. **
`Hermes_MANAGED=true

** biến môi trường - được đặt bởi dịch vụ systemd, hiển thị với quy trình cổng
2. **Tệp đánh dấu 

.managed

** trong 
`Hermes_HOME
` — được đặt theo tập lệnh kích hoạt, hiển thị với các hệ vỏ tương tác (ví dụ: 
`Docker exec -it Hermes-agent Hermes config set ...
` cũng bị chặn)

Để thay đổi cấu hình, hãy chỉnh sửa cấu hình Nix của bạn và chạy 
`sudo NixOS-rebuild switch

.

---

## Kiến trúc vùng chứa

:::info
Phần này chỉ phù hợp nếu bạn đang sử dụng 
`container.enable = true

. Bỏ qua nó để triển khai chế độ gốc.
:::

Khi chế độ vùng chứa được bật, Hermes chạy bên trong vùng chứa Ubuntu liên tục với chế độ chỉ đọc được gắn liên kết nhị phân do Nix xây dựng từ máy chủ:

`
Host                                    Container
────                                    ─────────
/nix/store/...-Hermes-agent-0.1.0  ──►  /nix/store/... (ro)
~/.Hermes -> /var/lib/Hermes/.Hermes       (symlink bridge, per hostUsers)
/var/lib/Hermes/                    ──►  /data/          (rw)
  ├── current-package -> /nix/store/...    (symlink, updated each rebuild)
  ├── .gc-root -> /nix/store/...           (prevents nix-collect-garbage)
  ├── .container-identity                  (sha256 hash, triggers recreation)
  ├── .Hermes/                             (Hermes_HOME)
  │   ├── .env                             (merged from environment + environmentFiles)
  │   ├── config.yaml                      (Nix-generated, deep-merged by activation)
  │   ├── .managed                         (marker file)
  │   ├── .container-mode                  (routing metadata: backend, exec_user, etc.)
  │   ├── state.db, sessions/, memories/   (runtime state)
  │   └── MCP-tokens/                      (OAuth tokens for MCP servers)
  ├── home/                                ──►  /home/Hermes    (rw)
  └── workspace/                           (MESSAGING_CWD)
      ├── SOUL.md                          (from documents option)
      └── (agent-created files)

Container writable layer (apt/pip/npm):   /usr, /usr/local, /tmp

`
``Tệp nhị phân do Nix xây dựng hoạt động bên trong bộ chứa Ubuntu vì 

/nix/store
` được gắn kết - nó mang theo trình thông dịch riêng và tất cả các phần phụ thuộc, do đó không phụ thuộc vào thư viện hệ thống của bộ chứa. Điểm vào vùng chứa phân giải thông qua liên kết tượng trưng 
`current-package

: 

/data/current-package/bin/Hermes gateway run --replace

. Trên 
`NixOS-rebuild switch

, chỉ liên kết tượng trưng được cập nhật - vùng chứa tiếp tục chạy.

### Điều gì tồn tại xuyên suốt điều gì

| Sự kiện | Vùng chứa được tạo lại? |

/data
` (trạng thái) | 

/home/Hermes
` | Lớp có thể ghi (
`apt

/
`pip

/
`npm

) |
|---|---|---|---|---|
| 
`systemctl restart Hermes-agent
` | Không | Kiên trì | Kiên trì | Kiên trì |
| 
`NixOS-rebuild switch
` (đổi mã) | Không (cập nhật liên kết tượng trưng) | Kiên trì | Kiên trì | Kiên trì |
| Khởi động lại máy chủ | Không | Kiên trì | Kiên trì | Kiên trì |
| 
`nix-collect-garbage
` | Không (gốc GC) | Kiên trì | Kiên trì | Kiên trì |
| Thay đổi hình ảnh (
`container.image

) | **Có** | Kiên trì | Kiên trì | **Mất** |
| Thay đổi âm lượng/tùy chọn | **Có** | Kiên trì | Kiên trì | **Mất** |
| Thay đổi 
`environment

/
`environmentFiles
` | Không | Kiên trì | Kiên trì | Kiên trì |

Vùng chứa chỉ được tạo lại khi **băm nhận dạng** của nó thay đổi. Hàm băm bao gồm: phiên bản lược đồ, hình ảnh, 
`extraVolumes

, 
`extraOptions
` và tập lệnh điểm nhập. Những thay đổi đối với biến môi trường, cài đặt, tài liệu hoặc bản thân gói Hermes **không** kích hoạt hoạt động giải trí.

:::warning[Writable layer loss]
Khi hàm băm nhận dạng thay đổi (nâng cấp hình ảnh, khối lượng mới, tùy chọn vùng chứa mới), vùng chứa sẽ bị hủy và được tạo lại từ một lần kéo mới của 
`container.image

. Mọi gói 
`apt install

, 
`pip install
` hoặc 
`npm install
` trong lớp có thể ghi đều bị mất. Trạng thái trong 

/data
` và 

/home/Hermes
` được giữ nguyên (đây là các giá trị gắn kết).

Nếu tác nhân dựa vào các gói cụ thể, hãy cân nhắc việc đưa chúng vào một hình ảnh tùy chỉnh (
`container.image = "my-registry/Hermes-base:latest"

) hoặc viết kịch bản cài đặt của chúng trong SOUL.md của tác nhân.
:::

### Bảo vệ gốc GC

Tập lệnh 
`preStart
` tạo gốc GC tại 

$\{stateDir}/.gc-root
` trỏ đến gói Hermes hiện tại. Điều này ngăn 
`nix-collect-garbage
` xóa tệp nhị phân đang chạy. Nếu root GC bằng cách nào đó bị hỏng, việc khởi động lại dịch vụ sẽ tạo lại nó.

---

## Plugin

Mô-đun NixOS hỗ trợ cài đặt plugin khai báo - không cần 
`Hermes plugins install
` bắt buộc.

### Plugin thư mục (
`extraPlugins

)

Đối với các plugin chỉ là cây nguồn có 
`plugin.YAML

 + 
`__init__.py
` (ví dụ: [Hermes-lcm](https://GitHub.com/stephenschoettler/Hermes-lcm)):

`nix
services.Hermes-agent.extraPlugins = [
  (pkgs.fetchFromGitHub {
    owner = "stephenschoettler";
    repo = "Hermes-lcm";
    rev = "v0.7.0";
    hash = "sha256-...";
  })
];

`
`Các plugin được liên kết tượng trưng với 

$Hermes_HOME/plugins/
` tại thời điểm kích hoạt. Hermes phát hiện ra chúng thông qua quá trình quét thư mục thông thường. Xóa plugin khỏi danh sách và chạy 
`NixOS-rebuild switch
` sẽ xóa liên kết tượng trưng.

### Plugin điểm đầu vào (
`extraPythonPackages

)

Đối với các plugin đóng gói pip đăng ký qua 

[project.entry-points."Hermes_agent.plugins"]
` (ví dụ: [rtk-Hermes](https://GitHub.com/ogallotti/rtk-Hermes)):

`nix
services.Hermes-agent.extraPythonPackages = [
  (pkgs.Python312Packages.buildPythonPackage {
    pname = "rtk-Hermes";
    version = "1.0.0";
    src = pkgs.fetchFromGitHub {
      owner = "ogallotti";
      repo = "rtk-Hermes";
      rev = "v1.0.0";
      hash = "sha256-...";
    };
    format = "pyproject";
    build-system = [ pkgs.Python312Packages.setuptools ];
  })
];

`
```site-packages
` của gói được thêm vào PythonPATH trong trình bao bọc Hermes. 
`importlib.metadata
` phát hiện điểm vào khi bắt đầu phiên.

### Nhóm phụ thuộc tùy chọn (
`extraDependencyGroups

)

Đối với các phần bổ sung tùy chọn đã được khai báo trong 
`pyproject.TOML
` của Hermes-agent (ví dụ: nhà cung cấp bộ nhớ như 
`hindsight
` hoặc 
`Honcho

), hãy sử dụng 
`extraDependencyGroups
` để đưa chúng vào venv kín tại thời điểm xây dựng:

`nix
services.Hermes-agent = &#123;
  extraDependencyGroups = [ "hindsight" ];
  settings.memory.provider = "hindsight";
&#125;;

`
``Điều này được giải quyết bằng tia cực tím cùng với các phần phụ thuộc cốt lõi chỉ trong một lần thực hiện — không cần vá PythonPATH, không có nguy cơ xung đột. Các nhóm có sẵn khớp với các khóa 

[project.optional-dependencies]
` trong 
`pyproject.TOML
` (ví dụ: 

"hindsight"

, 

"Honcho"

, 

"voice"

, 

"Matrix"

, 

"Mistral"

, 

"bedrock"

).

**Khi nào nên sử dụng cái nào:**

| Cần | Tùy chọn |
|------|--------|
| Kích hoạt thêm tùy chọn pyproject.TOML |

extraDependencyGroups
` |
| Thêm plugin Python bên ngoài không có trong pyproject.TOML |

extraPythonPackages
` |
| Thêm hệ thống nhị phân (pandoc, jq, v.v.) |

extraPackages
` |
| Thêm cây nguồn plugin dựa trên thư mục |

extraPlugins
` |

### Kết hợp cả hai

Một plugin thư mục có phần phụ thuộc Python của bên thứ ba cần có cả hai tùy chọn:

`nix
services.Hermes-agent = &#123;
  extraPlugins = [ my-plugin-src ];          # plugin source
  extraPythonPackages = [ pkgs.Python312Packages.Redis ];  # its Python dep
  extraPackages = [ pkgs.Redis ];            # system binary it needs
&#125;;

`

### Sử dụng Lớp phủ

Các vảy bên ngoài có thể ghi đè trực tiếp lên gói:

`nix
&#123;
  inputs.Hermes-agent.url = "GitHub:NousResearch/Hermes-agent";
  outputs = &#123; Hermes-agent, nixpkgs, ... &#125;: &#123;
    nixpkgs.overlays = [ Hermes-agent.overlays.default ];
    # Then:
    #   pkgs.Hermes-agent.override &#123; extraPythonPackages = [...]; &#125;
    #   pkgs.Hermes-agent.override &#123; extraDependencyGroups = [ "hindsight" ]; &#125;
  &#125;;
&#125;

`

### Cấu hình plugin

Các plugin vẫn cần được bật trong 
`config.yaml

. Thêm chúng thông qua cài đặt khai báo:

`nix
services.Hermes-agent.settings.plugins.enabled = [
  "Hermes-lcm"
  "rtk-rewrite"
];

`

:::note
Kiểm tra va chạm trong thời gian xây dựng sẽ ngăn các gói plugin che khuất các phần phụ thuộc cốt lõi của Hermes. Nếu plugin cung cấp gói đã có trong venv kín, 
`NixOS-rebuild
` không thành công với lỗi rõ ràng.
:::

---

## Phát triển

### Dev Shell

Flake cung cấp trình bao phát triển với Python 3.12, uv, Node.js và tất cả các công cụ thời gian chạy:

``` bash
cd Hermes-agent
nix develop

# Shell provides:

#   - Python 3.12 + uv (deps installed into .venv on first entry)
#   - Node.js 22, ripgrep, git, openSSH, ffmpeg on PATH
#   - Stamp-file optimization: re-entry is near-instant if deps haven't changed

Hermes setup
Hermes chat

`

### direnv (Được khuyến nghị)
.envrc
` đi kèm sẽ tự động kích hoạt dev shell:

``` bash
cd Hermes-agent
direnv allow    # one-time

# Subsequent entries are near-instant (stamp file skips dep install)

`

### Kiểm tra vảy

Phần mềm này bao gồm xác minh tại thời điểm xây dựng chạy trong CI và cục bộ:

``` bash

# Run all checks
nix flake check

# Individual checks
nix build .#checks.x86_64-Linux.package-contents   # binaries exist + version
nix build .#checks.x86_64-Linux.entry-points-sync  # pyproject.TOML ↔ Nix package sync
nix build .#checks.x86_64-Linux.CLI-commands        # gateway/config subcommands
nix build .#checks.x86_64-Linux.managed-guard       # Hermes_MANAGED blocks mutation
nix build .#checks.x86_64-Linux.bundled-skills      # skills present in package
nix build .#checks.x86_64-Linux.config-roundtrip    # merge script preserves user keys

`
``&lt;details
&lt;summary&lt;strongMỗi lần kiểm tra xác minh điều gì&lt;/strong&lt;/summary

| Kiểm tra | Nó kiểm tra cái gì |
|---|---|
| 
`package-contents
` | Các nhị phân 
`Hermes
` và 
`Hermes-agent
` tồn tại và 
`Hermes version
` chạy |
| 
`entry-points-sync
` | Mỗi mục nhập 

[project.scripts]
` trong 
`pyproject.TOML
` đều có tệp nhị phân được gói trong gói Nix |
| 
`CLI-commands
` | 
`Hermes --help
` hiển thị các lệnh phụ 
`gateway
` và 
`config
` |
| 
`managed-guard
` | 
`Hermes_MANAGED=true Hermes config set ...
` in lỗi NixOS |
| 
`bundled-skills
` | Thư mục kỹ năng tồn tại, chứa các tệp SKILL.md, 
`Hermes_BUNDLED_SKILLS
` được đặt trong trình bao bọc |
| 
`config-roundtrip
` | 7 kịch bản hợp nhất: cài đặt mới, ghi đè Nix, bảo toàn khóa người dùng, hợp nhất hỗn hợp, hợp nhất phụ gia MCP, hợp nhất sâu lồng nhau, idempotency |

&lt;/details

---

## Tùy chọn Tham khảo

### Cốt lõi

| Tùy chọn | Loại | Mặc định | Mô tả |
|---|---|---|---|
| 
`enable
` | 
`bool
` | 
`false
` | Kích hoạt dịch vụ đại lý Hermes |
| 
`package
` | 
`package
` | 
`Hermes-agent
` | Gói Hermes-agent để sử dụng |
| 
`user
` | 
`str
` | 

"Hermes"
` | Người dùng hệ thống |
| 
`group
` | 
`str
` | 

"Hermes"
` | Nhóm hệ thống |
| 
`createUser
` | 
`bool
` | 
`true
` | Tự động tạo người dùng/nhóm |
| 
`stateDir
` | 
`str
` | 

"/var/lib/Hermes"
` | Thư mục trạng thái (mẹ 
`Hermes_HOME

) |
| 
`workingDirectory
` | 
`str
` | 

"$\&#123;stateDir&#125;/workspace"
` | Thư mục làm việc của đại lý (
`MESSAGING_CWD

) |
| 
`addToSystemPackages
` | 
`bool
` | 
`false
` | Thêm 
`Hermes
` CLI vào PATH hệ thống và đặt 
`Hermes_HOME
` trên toàn hệ thống |

### Cấu hình| Tùy chọn | Loại | Mặc định | Mô tả |
|---|---|---|---|
| 
`settings
` | 
`attrs
` (được hợp nhất sâu) | 

\&#123;&#125;
` | Cấu hình khai báo được hiển thị dưới dạng 
`config.yaml

. Hỗ trợ lồng tùy ý; nhiều định nghĩa được hợp nhất thông qua 
`lib.recursiveUpdate
` |
| 
`configFile
` | 
`null
` hoặc 
`path
` | 
`null
` | Đường dẫn đến 
`config.yaml
` hiện có. Ghi đè hoàn toàn 
`settings
` nếu được đặt |

### Bí mật & Môi trường

| Tùy chọn | Loại | Mặc định | Mô tả |
|---|---|---|---|
| 
`environmentFiles
` | 
`listOf str
` | 

[]
` | Đường dẫn đến tệp env có bí mật. Được sáp nhập vào 

$Hermes_HOME/.env
` tại thời điểm kích hoạt |
| 
`environment
` | 
`attrsOf str
` | 

\&#123;&#125;
` | Các loại env không bí mật. **Hiển thị trong cửa hàng Nix** — không đặt bí mật ở đây |
| 
`authFile
` | 
`null
` hoặc 
`path
` | 
`null
` | Hạt giống thông tin xác thực OAuth. Chỉ được sao chép trong lần triển khai đầu tiên |
| 
`authFileForceOverwrite
` | 
`bool
` | 
`false
` | Luôn ghi đè 
`auth.JSON
` từ 
`authFile
` khi kích hoạt |

### Tài liệu

| Tùy chọn | Loại | Mặc định | Mô tả |
|---|---|---|---|
| 
`documents
` | 
`attrsOf (either str path)
` | 

\&#123;&#125;
` | Các tập tin không gian làm việc. Khóa là tên tệp, giá trị là chuỗi nội tuyến hoặc đường dẫn. Đã cài đặt vào 
`workingDirectory
` khi kích hoạt |

### Máy chủ MCP

| Tùy chọn | Loại | Mặc định | Mô tả |
|---|---|---|---|
| 
`MCPServers
` | 
`attrsOf submodule
` | 

\&#123;&#125;
` | Định nghĩa máy chủ MCP, được sáp nhập vào 
`settings.MCP_servers
` |
| 
`MCPServers.&lt;name.command
` | 
`null
` hoặc 
`str
` | 
`null
` | Lệnh máy chủ (stdio Transport) |
| 
`MCPServers.&lt;name.args
` | 
`listOf str
` | 

[]
` | Đối số lệnh |
| 
`MCPServers.&lt;name.env
` | 
`attrsOf str
` | 

\&#123;&#125;
` | Biến môi trường cho tiến trình máy chủ |
| 
`MCPServers.&lt;name.url
` | 
`null
` hoặc 
`str
` | 
`null
` | URL điểm cuối của máy chủ (truyền tải HTTP/StreamableHTTP) |
| 
`MCPServers.&lt;name.headers
` | 
`attrsOf str
` | 

\&#123;&#125;
` | Tiêu đề HTTP, ví dụ: 
`Authorization
` |
| 
`MCPServers.&lt;name.auth
` | 
`null
` hoặc 

"OAuth"
` | 
`null
` | Phương pháp xác thực. 

"OAuth"
` kích hoạt OAuth 2.1 PKCE |
| 
`MCPServers.&lt;name.enabled
` | 
`bool
` | 
`true
` | Bật hoặc tắt máy chủ này |
| 
`MCPServers.&lt;name.timeout
` | 
`null
` hoặc 
`int
` | 
`null
` | Thời gian chờ cuộc gọi công cụ tính bằng giây (mặc định: 120) |
| 
`MCPServers.&lt;name.connect_timeout
` | 
`null
` hoặc 
`int
` | 
`null
` | Thời gian chờ kết nối tính bằng giây (mặc định: 60) |
| 
`MCPServers.&lt;name.tools
` | 
`null
` hoặc 
`submodule
` | 
`null
` | Lọc công cụ (danh sách 
`include

/
`exclude

) |
| 
`MCPServers.&lt;name.sampling
` | 
`null
` hoặc 
`submodule
` | 
`null
` | Cấu hình lấy mẫu cho các yêu cầu LLM do máy chủ khởi tạo |

###Hành vi phục vụ

| Tùy chọn | Loại | Mặc định | Mô tả |
|---|---|---|---|
| 
`extraArgs
` | 
`listOf str
` | 

[]
` | Đối số bổ sung cho 
`Hermes gateway
` |
| 
`extraPackages
` | 
`listOf package
` | 

[]
` | Các gói bổ sung có sẵn cho đại lý. Đã thêm vào hồ sơ mỗi người dùng của người dùng Hermes để tất cả các lệnh đầu cuối, kỹ năng và công việc định kỳ đều nhìn thấy chúng |
| 
`extraPlugins
` | 
`listOf package
` | 

[]
` | Thư mục các gói plugin để liên kết tượng trưng vào 

$Hermes_HOME/plugins/

. Mỗi cái phải chứa 
`plugin.YAML
` |
| 
`extraPythonPackages
` | 
`listOf package
` | 

[]
` | Các gói Python được thêm vào PythonPATH để khám phá plugin điểm đầu vào. Xây dựng với 
`Python312Packages
` |
| 
`extraDependencyGroups
` | 
`listOf str
` | 

[]
` | Các phần bổ sung tùy chọn của pyproject.TOML để bao gồm trong venv kín (ví dụ: 

["hindsight"]

). Đã giải quyết bằng tia cực tím — không có va chạm |
| 
`restart
` | 
`str
` | 

"always"
` | chính sách systemd 
`Restart=
` |
| 
`restartSec
` | 
`int
` | 
`5
` | giá trị systemd 
`RestartSec=
` |

### Thùng chứa| Tùy chọn | Loại | Mặc định | Mô tả |
|---|---|---|---|
| 
`container.enable
` | 
`bool
` | 
`false
` | Kích hoạt chế độ vùng chứa OCI |
| 
`container.backend
` | 
`enum ["Docker" "podman"]
` | 

"Docker"
` | Thời gian chạy vùng chứa |
| 
`container.image
` | 
`str
` | 

"ubuntu:24.04"
` | Hình ảnh cơ sở (được kéo khi chạy) |
| 
`container.extraVolumes
` | 
`listOf str
` | 

[]
` | Giá đỡ âm lượng bổ sung (
`host:container:mode

) |
| 
`container.extraOptions
` | 
`listOf str
` | 

[]
` | Các đối số bổ sung được chuyển tới 
`Docker create
` |
| 
`container.hostUsers
` | 
`listOf str
` | 

[]
` | Người dùng tương tác nhận được liên kết tượng trưng 

~/.Hermes
` đến dịch vụ stateDir và được tự động thêm vào nhóm 
`Hermes
` |

---

## Bố cục thư mục

### Chế độ gốc

`
/var/lib/Hermes/                     # stateDir (owned by Hermes:Hermes, 0750)
├── .Hermes/                         # Hermes_HOME
│   ├── config.yaml                  # Nix-generated (deep-merged each rebuild)
│   ├── .managed                     # Marker: CLI config mutation blocked
│   ├── .env                         # Merged from environment + environmentFiles
│   ├── auth.JSON                    # OAuth credentials (seeded, then self-managed)
│   ├── gateway.pid
│   ├── state.db
│   ├── MCP-tokens/                  # OAuth tokens for MCP servers
│   ├── sessions/
│   ├── memories/
│   ├── skills/
│   ├── cron/
│   └── logs/
├── home/                            # Agent HOME
└── workspace/                       # MESSAGING_CWD
    ├── SOUL.md                      # From documents option
    └── (agent-created files)

`

### Chế độ vùng chứa

Bố cục tương tự, được gắn vào thùng chứa:

| Đường dẫn container | Đường dẫn máy chủ | Chế độ | Ghi chú |
|---|---|---|---|
| 

/nix/store
` | 

/nix/store
` | 
`ro
` | Hệ nhị phân Hermes + tất cả các chi tiết Nix |
| 

/data
` | 

/var/lib/Hermes
` | 
`rw
` | Tất cả trạng thái, cấu hình, không gian làm việc |
| 

/home/Hermes
` | 

$\&#123;stateDir&#125;/home
` | 
`rw
` | Trang chủ đại lý liên tục — 
`pip install --user

, bộ đệm công cụ |
| 

/usr

, 

/usr/local

, 

/tmp
` | (lớp có thể ghi) |

rw
` | Số lượt cài đặt 
`apt

/
`pip

/
`npm
` — vẫn tồn tại sau khi khởi động lại, bị mất khi giải trí |

---

## Đang cập nhật

``` bash

# Update the flake input (run from the directory containing flake.nix)
cd /etc/NixOS && nix flake update Hermes-agent

# Rebuild
sudo NixOS-rebuild switch

`
``Ở chế độ vùng chứa, liên kết tượng trưng 
`current-package
` được cập nhật và tác nhân chọn tệp nhị phân mới khi khởi động lại. Không giải trí container, không mất gói đã cài đặt.

---

## Khắc phục sự cố

:::tip[Podman users]
Tất cả các lệnh 
`Docker
` bên dưới đều hoạt động tương tự với 
`podman

. Thay thế tương ứng nếu bạn đặt 
`container.backend = "podman"

.
:::

### Nhật ký dịch vụ

``` bash

# Both modes use the same systemd unit
journalctl -u Hermes-agent -f

# Container mode: also available directly
Docker logs -f Hermes-agent

`
``###Kiểm tra container

``` bash
systemctl status Hermes-agent
Docker ps -a --filter name=Hermes-agent
Docker inspect Hermes-agent --format='\&#123;\&#123;.State.Status&#125;&#125;'
Docker exec -it Hermes-agent bash
Docker exec Hermes-agent readlink /data/current-package
Docker exec Hermes-agent cat /data/.container-identity

`

### Giải trí Force Container

Nếu bạn cần đặt lại lớp có thể ghi (Ubuntu mới):

`bash
sudo systemctl stop Hermes-agent
Docker rm -f Hermes-agent
sudo rm /var/lib/Hermes/.container-identity
sudo systemctl start Hermes-agent

`

### Xác minh bí mật đã được tải

Nếu tác nhân khởi động nhưng không thể xác thực với nhà cung cấp LLM, hãy kiểm tra xem tệp 

.env
` đã được hợp nhất chính xác chưa:

`bash

# Native mode
sudo -u Hermes cat /var/lib/Hermes/.Hermes/.env

# Container mode
Docker exec Hermes-agent cat /data/.Hermes/.env

`

### Xác minh gốc GC

``` bash
nix-store --query --roots $(Docker exec Hermes-agent readlink /data/current-package)

`

### Các vấn đề thường gặp

| Triệu chứng | Nguyên nhân | Sửa chữa |
|---|---|---|
| 
`Cannot save configuration: managed by NixOS
` | Bảo vệ CLI đang hoạt động | Chỉnh sửa 
`configuration.nix
` và 
`NixOS-rebuild switch
` |
| Container được tạo lại bất ngờ |

extraVolumes

, 
`extraOptions
` hoặc 
`image
` đã thay đổi | Dự kiến ​​- đặt lại lớp có thể ghi. Cài đặt lại các gói hoặc sử dụng hình ảnh tùy chỉnh |
| 
`Hermes version
` hiển thị phiên bản cũ | Vùng chứa chưa được khởi động lại |

systemctl restart Hermes-agent
` |
| Quyền bị từ chối trên 

/var/lib/Hermes
` | Thư mục trạng thái là 
`0750 Hermes:Hermes
` | Sử dụng 
`Docker exec
` hoặc 
`sudo -u Hermes
` |
| 
`nix-collect-garbage
` đã loại bỏ Hermes | Thiếu gốc GC | Khởi động lại dịch vụ (preStart tạo lại gốc GC) |
| 
`no container with name or ID "Hermes-agent"
` (Podman) | Vùng chứa gốc của Podman không hiển thị với người dùng thông thường | Thêm sudo không mật khẩu cho podman (xem phần [Container Mode](#container-mode)) |
| 
`unable to find user Hermes
` | Vùng chứa vẫn đang bắt đầu (điểm vào chưa tạo người dùng) | Đợi vài giây và thử lại - CLI tự động thử lại |
| Không tìm thấy công cụ được thêm qua 
`extraPackages
` trong terminal | Yêu cầu 
`NixOS-rebuild switch
` cập nhật hồ sơ mỗi người dùng | Xây dựng lại và khởi động lại: 
`NixOS-rebuild switch && systemctl restart Hermes-agent
` |