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

curl | trình cài đặt 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 có 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 đó (thiết lập hermes, cài đặt cổng hermes, chỉnh sửa cấu hình) hoạt động giống hệt với quá trình 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, 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 — Xác định Nix được đề xuất (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 cài đặt tiêu chuẩn — 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 nằm trong ~/.hermes/.

Building from a local clone

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
nix build
./result/bin/hermes setup

Mô-đun NixOS

Flake 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ụ.

ghi chú

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

# /etc/nixos/flake.nix (or your system flake)
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
    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

# 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 các 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.

Secrets are required

Dòng environmentFiles ở trên giả sử bạn đã định cấu hình sops-nix hoặc 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 Quản lý bí mật để biết thông tin 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:

echo "OPENROUTER_API_KEY=sk-or-your-key" | sudo install -m 0600 -o hermes /dev/stdin /var/lib/hermes/env

services.hermes-agent.environmentFiles = [ "/var/lib/hermes/env" ];

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 biệt.

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:

# 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 này 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 tiếp tục trong suốt quá trình 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:

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

thông tin

Chế độ vùng chứa tự động kích hoạt virtualisation.docker.enable thông qua mkDefault. Thay vào đó, nếu bạn sử dụng Podman, 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 một attrset 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 thành các tệp:

# 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, thì chúng vẫn tồn tại trong nixos-rebuild switch.

Model naming

settings.model.default sử dụng mã định danh mô hình mà nhà cung cấp của bạn mong đợi. Với OpenRouter (mặc định), các tệp này 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 có base_url nào được đặt, Hermes sẽ mặc định là OpenRouter.

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 tin settings — bản đồ cấu trúc 1:1.

Full example: all commonly customized settings

{ 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 = {
      "SOUL.md" = builtins.readFile /home/user/.hermes/SOUL.md;
      "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";
      extraVolumes = [ "/home/user/projects:/projects:rw" ];
      extraOptions = [ "--gpus" "all" ];
    };

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

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

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

services.hermes-agent.configFile = /etc/hermes/config.yaml;

Điều này bỏ qua hoàn toàn cài đặt - không hợp nhất, không tạo. Tệp được sao chép nguyên trạng vào $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`	`"nhân chủng/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	`môi trườngFiles`	`[ config.sops.secrets."hermes-env".path ]`
Tạo cá tính cho đại lý	`tài liệu."SOUL.md"`	`buildins.readFile ./my-soul.md`
Thêm máy chủ công cụ MCP	`mcpServers.<name>`	Xem Máy chủ MCP
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" "tất cả" ]`
Sử dụng Podman thay vì Docker	`container.backend`	`"podman"`
Thêm công cụ vào dịch vụ PATH (chỉ bản địa)	`Gói bổ sung`	`[ 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	`gói`	`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ý	`Thư mục làm việc`	`"/home/user/dự án"`

Quản lý bí mật

Never put API keys in settings or environment

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 (file 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

{
  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ị:

# secrets/hermes.yaml (encrypted with sops)
hermes-env: |
    OPENROUTER_API_KEY=sk-or-...
    TELEGRAM_BOT_TOKEN=123456:ABC...
    ANTHROPIC_API_KEY=sk-ant-...

###agenix

{
  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:

{
  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:

SOUL.md — lời nhắc/tính cách hệ thống của đại lý. Hermes đọc điều này khi khởi động và sử dụng nó như những hướng dẫn liên tục định hình hành vi của nó trong tất cả các cuộc trò chuyện.
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.

{
  services.hermes-agent.documents = {
    "SOUL.md" = ''
      You are a helpful research assistant specializing in NixOS packaging.
      Always cite sources and prefer reproducible solutions.
    '';
    "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 tin được cài đặt trên mọi nixos-rebuild switch.

Máy chủ MCP

Tùy chọn mcpServers định cấu hình khai báo các máy chủ MCP (Model Context Protocol). 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ộ)

{
  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
    };
  };
}

mẹo

Các biến môi trường trong giá trị env được phân giải từ $HERMES_HOME/.env khi chạy. Sử dụng environmentFiles để chèn 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)

{
  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 các 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.

{
  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/<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.

Initial OAuth authorization on headless servers

Ủ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: Bootstrap tương tác — chạy luồng một lần thông qua docker exec (container) hoặc sudo -u hermes (gốc):

# 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:

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

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:

{
  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 bị chặn với lỗi mô tả hướng bạn đến configuration.nix:

Lệnh bị chặn	Tại sao
`thiết lập hermes`	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
`chỉnh sửa cấu hình Hermes`	Cấu hình được tạo từ `settings`
`bộ cấu hình Hermes <key> <value>`	Cấu hình được tạo từ `settings`
`cài đặt cổng Hermes`	Dịch vụ systemd được quản lý bởi NixOS
`gỡ cài đặt cổng hermes`	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:

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
.managed tập tin đánh dấu trong HERMES_HOME — được thiết lập bởi tập lệnh kích hoạt, hiển thị với các shell 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

thông tin

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)
/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)
  │   ├── 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 liê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ỉ có liên kết tượng trưng được cập nhật - vùng chứa vẫn 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 khởi động lại Hermes-agent`	Không	Kiên trì	Kiên trì	Kiên trì
`nixos-rebuild switch` (thay đổ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-thu thập-rác`	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
`môi trường`/`environmentFiles` thay đổi	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 các 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í.

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 liên kết 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 một 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ó.

Phát triển

Dev Shell

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

cd hermes-agent
nix develop

# Shell provides:
#   - Python 3.11 + uv (deps installed into .venv on first entry)
#   - Node.js 20, 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 shell dev:

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ộ:

# 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

What each check verifies

Kiểm tra	Nó kiểm tra cái gì
`nội dung gói`	Các nhị phân `hermes` và `hermes-agent` tồn tại và `hermes version` chạy
`đồng bộ điểm vào`	Mỗi mục nhập `[project.scripts]` trong `pyproject.toml` đều có một tệp nhị phân được gói trong gói Nix
`cli-lệnh`	`hermes --help` hiển thị các lệnh con `gateway` và `config`
`bảo vệ được quản lý`	`HERMES_MANAGED=true bộ cấu hình Hermes ...` in lỗi NixOS
`kỹ năng đi kèm`	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-khứ hồi`	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

Tùy chọn Tham khảo

Cốt lõi

Tùy chọn	Loại	Mặc định	Mô tả
`kích hoạt`	`bool`	`sai`	Kích hoạt dịch vụ đại lý Hermes
`gói`	`gói`	`đại lý Hermes`	Gói Hermes-agent để sử dụng
`người dùng`	`str`	`"hermes"`	Người dùng hệ thống
`nhóm`	`str`	`"hermes"`	Nhóm hệ thống
`tạoNgười dùng`	`bool`	`đúng`	Tự động tạo người dùng/nhóm
`stateDir`	`str`	`"/var/lib/hermes"`	Thư mục trạng thái (cha mẹ `HERMES_HOME`)
`Thư mục làm việc`	`str`	`"${stateDir}/workspace"`	Thư mục làm việc của đại lý (`MESSAGING_CWD`)
`addToSystemPackages`	`bool`	`sai`	Thêm `hermes` CLI vào hệ thống PATH và đặt `HERMES_HOME` toàn hệ thống

Cấu hình

Tùy chọn	Loại	Mặc định	Mô tả
`cài đặt`	`attrs` (được hợp nhất sâu)	`{}`	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ả
`môi trườngFiles`	`listOfstr`	`[]`	Đường dẫn đến tệp env có bí mật. Đã sáp nhập vào `$HERMES_HOME/.env` tại thời điểm kích hoạt
`môi trường`	`attrsOf str`	`{}`	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`	`sai`	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ả
`tài liệu`	`attrsOf (hoặc đường dẫn str)`	`{}`	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 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 mô-đun con`	`{}`	Định nghĩa máy chủ MCP, được hợp nhất vào `settings.mcp_servers`
`mcpServers.<name>.command`	`null` hoặc `str`	`null`	Lệnh máy chủ (stdio Transport)
`mcpServers.<name>.args`	`listOfstr`	`[]`	Đối số lệnh
`mcpServers.<name>.env`	`attrsOf str`	`{}`	Biến môi trường cho tiến trình máy chủ
`mcpServers.<name>.url`	`null` hoặc `str`	`null`	URL điểm cuối của máy chủ (truyền tải HTTP/StreamableHTTP)
`mcpServers.<name>.headers`	`attrsOf str`	`{}`	Tiêu đề HTTP, ví dụ: `Ủy quyền`
`mcpServers.<name>.auth`	`null` hoặc `"oauth"`	`null`	Phương pháp xác thực. `"oauth"` bật OAuth 2.1 PKCE
`mcpServers.<name>.enabled`	`bool`	`đúng`	Bật hoặc tắt máy chủ này
`mcpServers.<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.<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.<name>.tools`	`null` hoặc `mô-đun con`	`null`	Lọc công cụ (danh sách `bao gồm`/`loại trừ`)
`mcpServers.<name>.sampling`	`null` hoặc `mô-đun con`	`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`	`listOfstr`	`[]`	Lập luận bổ sung cho ``hermes Gateway`
`Gói bổ sung`	`danh sách gói`	`[]`	Các gói bổ sung trên dịch vụ PATH (chỉ ở chế độ gốc)
`khởi động lại`	`str`	`"luôn luôn"`	systemd `Khởi động lại=` chính sách
`khởi động lạiSec`	`int`	`5`	systemd `RestartSec=` giá trị

Thùng chứa

Tùy chọn	Loại	Mặc định	Mô tả
`container.enable`	`bool`	`sai`	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`	`listOfstr`	`[]`	Gắn kết âm lượng bổ sung (`host:container:mode`)
`container.extraOptions`	`listOfstr`	`[]`	Các đối số bổ sung được chuyển tới `docker create`

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
`/dữ liệu`	`/var/lib/hermes`	`rw`	Tất cả trạng thái, cấu hình, không gian làm việc
`/home/hermes`	`${stateDir}/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`	`apt`/`pip`/`npm` cài đặt — 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

# Update the flake input
nix flake update hermes-agent --flake /etc/nixos

# Rebuild
sudo nixos-rebuild switch

Trong 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ố

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ụ

# 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

systemctl status hermes-agent
docker ps -a --filter name=hermes-agent
docker inspect hermes-agent --format='{{.State.Status}}'
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):

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:

# 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

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
`Không lưu được cấu hình: do NixOS quản lý`	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
`phiên bản Hermes` hiển thị phiên bản cũ	Vùng chứa chưa được khởi động lại	`systemctl khởi động lại 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)

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

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

Mô-đun NixOS​

Thêm đầu vào Flake​

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

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

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

Cấu hình​

Cài đặt khai báo​

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

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

Quản lý bí mật​

sops-nix​

OAuth / Auth Seeding​

Tài liệu​

Máy chủ MCP​

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

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

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

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

Chế độ quản lý​

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

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

Bảo vệ gốc GC​

Phát triển​

Dev Shell​

direnv (Được khuyến nghị)​

Kiểm tra vảy​

Tùy chọn Tham khảo​

Cốt lõi​

Cấu hình​

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

Tài liệu​

Máy chủ MCP​

Thùng chứa​

Bố cục thư mục​

Chế độ gốc​

Chế độ vùng chứa​

Đang cập nhật​

Khắc phục sự cố​

Nhật ký dịch vụ​

Giải trí Force Container​

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

Xác minh gốc GC​

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

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

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

Mô-đun NixOS

Thêm đầu vào Flake

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

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

Chọn Chế độ Triển khai

Cấu hình

Cài đặt khai báo

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

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

Quản lý bí mật

sops-nix

OAuth / Auth Seeding

Tài liệu

Máy chủ MCP

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

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

Truyền tải HTTP với OAuth

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

Chế độ quản lý

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

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

Bảo vệ gốc GC

Phát triển

Dev Shell

direnv (Được khuyến nghị)

Kiểm tra vảy

Tùy chọn Tham khảo

Cốt lõi

Cấu hình

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

Tài liệu

Máy chủ MCP

Thùng chứa

Bố cục thư mục

Chế độ gốc

Chế độ vùng chứa

Đang cập nhật

Khắc phục sự cố

Nhật ký dịch vụ

Giải trí Force Container

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

Xác minh gốc GC

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