mirror of
https://github.com/0xrsydn/nix-hermes-agent.git
synced 2026-08-07 00:53:52 +00:00
feat: declarative NixOS module following nix-openclaw patterns
- Deep-merge config attrset → cli-config.yaml (like nix-openclaw's JSON config) - Declarative documents option (SOUL.md, AGENTS.md, USER.md — inline or file paths) - MCP servers as structured Nix options (merged into config) - Environment files for secrets (systemd EnvironmentFile, outside Nix store) - Non-secret environment vars (separate from secrets) - Proper tmpfiles rules, activation scripts for config + document linking - systemd hardening (NoNewPrivileges, ProtectSystem, PrivateTmp) - Comprehensive README with full usage examples
This commit is contained in:
Ciphercat
parent
f70dc0f39b
commit
3dd03ba2ae
2 changed files with 437 additions and 92 deletions
327
module.nix
327
module.nix
|
|
@ -4,122 +4,329 @@ self:
|
|||
let
|
||||
cfg = config.services.hermes-agent;
|
||||
hermes-agent = self.packages.${pkgs.system}.hermes-agent;
|
||||
|
||||
# Deep-merge config type (same pattern as nix-openclaw)
|
||||
deepConfigType = lib.types.mkOptionType {
|
||||
name = "hermes-config-attrs";
|
||||
description = "Hermes YAML config (attrset), merged deeply via lib.recursiveUpdate.";
|
||||
check = builtins.isAttrs;
|
||||
merge = _loc: defs: lib.foldl' lib.recursiveUpdate { } (map (d: d.value) defs);
|
||||
};
|
||||
|
||||
# Convert Nix attrset → YAML via JSON intermediary
|
||||
# (Hermes reads YAML but YAML is a superset of JSON, so JSON works)
|
||||
configJson = builtins.toJSON cfg.config;
|
||||
generatedConfigFile = pkgs.writeText "cli-config.yaml" configJson;
|
||||
configFile = if cfg.configFile != null then cfg.configFile else generatedConfigFile;
|
||||
|
||||
# Generate .env file from environment attrset (non-secret env vars)
|
||||
envFileContent = lib.concatStringsSep "\n" (
|
||||
lib.mapAttrsToList (k: v: "${k}=${v}") cfg.environment
|
||||
);
|
||||
generatedEnvFile = pkgs.writeText "hermes-env" envFileContent;
|
||||
|
||||
# Document files → symlinked into workspace
|
||||
documentDerivation = pkgs.runCommand "hermes-documents" { } (
|
||||
''
|
||||
mkdir -p $out
|
||||
'' + lib.concatStringsSep "\n" (
|
||||
lib.mapAttrsToList (name: value:
|
||||
if builtins.isPath value || lib.isStorePath value
|
||||
then "cp ${value} $out/${name}"
|
||||
else "cat > $out/${name} <<'HERMES_DOC_EOF'\n${value}\nHERMES_DOC_EOF"
|
||||
) cfg.documents
|
||||
)
|
||||
);
|
||||
|
||||
in
|
||||
{
|
||||
options.services.hermes-agent = {
|
||||
enable = lib.mkEnableOption "Hermes Agent gateway service";
|
||||
options.services.hermes-agent = with lib; {
|
||||
enable = mkEnableOption "Hermes Agent gateway service";
|
||||
|
||||
package = lib.mkOption {
|
||||
type = lib.types.package;
|
||||
# ── Package ──────────────────────────────────────────────────────────
|
||||
package = mkOption {
|
||||
type = types.package;
|
||||
default = hermes-agent;
|
||||
description = "The hermes-agent package to use.";
|
||||
};
|
||||
|
||||
user = lib.mkOption {
|
||||
type = lib.types.str;
|
||||
default = "hermes";
|
||||
description = "User under which Hermes Agent runs.";
|
||||
# ── Service identity ─────────────────────────────────────────────────
|
||||
unitName = mkOption {
|
||||
type = types.str;
|
||||
default = "hermes-agent";
|
||||
description = "systemd unit name (<unitName>.service).";
|
||||
};
|
||||
|
||||
group = lib.mkOption {
|
||||
type = lib.types.str;
|
||||
user = mkOption {
|
||||
type = types.str;
|
||||
default = "hermes";
|
||||
description = "Group under which Hermes Agent runs.";
|
||||
description = "System user running the gateway.";
|
||||
};
|
||||
|
||||
homeDir = lib.mkOption {
|
||||
type = lib.types.path;
|
||||
group = mkOption {
|
||||
type = types.str;
|
||||
default = "hermes";
|
||||
description = "System group running the gateway.";
|
||||
};
|
||||
|
||||
createUser = mkOption {
|
||||
type = types.bool;
|
||||
default = true;
|
||||
description = "Create the user/group automatically.";
|
||||
};
|
||||
|
||||
# ── Directories ──────────────────────────────────────────────────────
|
||||
stateDir = mkOption {
|
||||
type = types.str;
|
||||
default = "/var/lib/hermes";
|
||||
description = "Home directory for Hermes Agent state.";
|
||||
description = "State directory (HERMES_HOME base). Contains .hermes/ subdir.";
|
||||
};
|
||||
|
||||
workDir = lib.mkOption {
|
||||
type = lib.types.path;
|
||||
default = "${cfg.homeDir}/workspace";
|
||||
defaultText = lib.literalExpression ''"''${cfg.homeDir}/workspace"'';
|
||||
description = "Working directory for Hermes Agent.";
|
||||
workingDirectory = mkOption {
|
||||
type = types.str;
|
||||
default = "${cfg.stateDir}/workspace";
|
||||
defaultText = literalExpression ''"''${cfg.stateDir}/workspace"'';
|
||||
description = "Working directory for the agent (MESSAGING_CWD).";
|
||||
};
|
||||
|
||||
environmentFile = lib.mkOption {
|
||||
type = lib.types.nullOr lib.types.path;
|
||||
# ── Config (declarative YAML) ────────────────────────────────────────
|
||||
configFile = mkOption {
|
||||
type = types.nullOr types.path;
|
||||
default = null;
|
||||
description = ''
|
||||
Path to an environment file containing secrets (API keys, tokens).
|
||||
This file should contain lines like:
|
||||
ANTHROPIC_API_KEY=sk-...
|
||||
TELEGRAM_TOKEN=...
|
||||
OPENROUTER_API_KEY=...
|
||||
Path to an existing cli-config.yaml. If set, takes precedence over
|
||||
the declarative `config` option.
|
||||
'';
|
||||
};
|
||||
|
||||
extraEnvironment = lib.mkOption {
|
||||
type = lib.types.attrsOf lib.types.str;
|
||||
config = mkOption {
|
||||
type = deepConfigType;
|
||||
default = { };
|
||||
description = "Extra environment variables for the Hermes Agent service.";
|
||||
example = lib.literalExpression ''
|
||||
description = ''
|
||||
Declarative Hermes config (attrset). Deep-merged across module definitions
|
||||
and rendered as cli-config.yaml. See upstream cli-config.yaml.example for
|
||||
all available keys.
|
||||
'';
|
||||
example = literalExpression ''
|
||||
{
|
||||
HERMES_DEFAULT_MODEL = "anthropic/claude-sonnet-4-20250514";
|
||||
model = {
|
||||
default = "anthropic/claude-sonnet-4-20250514";
|
||||
provider = "openrouter";
|
||||
};
|
||||
terminal = {
|
||||
backend = "local";
|
||||
timeout = 180;
|
||||
};
|
||||
agent = {
|
||||
max_turns = 60;
|
||||
reasoning_effort = "medium";
|
||||
};
|
||||
memory = {
|
||||
memory_enabled = true;
|
||||
user_profile_enabled = true;
|
||||
};
|
||||
toolsets = [ "all" ];
|
||||
}
|
||||
'';
|
||||
};
|
||||
|
||||
extraArgs = lib.mkOption {
|
||||
type = lib.types.listOf lib.types.str;
|
||||
# ── Secrets / environment ────────────────────────────────────────────
|
||||
environmentFiles = mkOption {
|
||||
type = types.listOf types.str;
|
||||
default = [ ];
|
||||
description = "Extra command-line arguments to pass to hermes gateway.";
|
||||
description = ''
|
||||
Paths to environment files containing secrets (API keys, tokens).
|
||||
These are passed as systemd EnvironmentFile= entries.
|
||||
Use leading '-' to ignore missing files.
|
||||
|
||||
Example file contents:
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
OPENROUTER_API_KEY=sk-or-...
|
||||
TELEGRAM_TOKEN=123456:ABC...
|
||||
'';
|
||||
};
|
||||
|
||||
extraPackages = lib.mkOption {
|
||||
type = lib.types.listOf lib.types.package;
|
||||
environment = mkOption {
|
||||
type = types.attrsOf types.str;
|
||||
default = { };
|
||||
description = ''
|
||||
Non-secret environment variables for Hermes. These are written to
|
||||
an env file (visible in the Nix store — do NOT put secrets here).
|
||||
Use `environmentFiles` for secrets.
|
||||
'';
|
||||
example = literalExpression ''
|
||||
{
|
||||
LLM_MODEL = "anthropic/claude-opus-4.6";
|
||||
MESSAGING_CWD = "/var/lib/hermes/workspace";
|
||||
}
|
||||
'';
|
||||
};
|
||||
|
||||
# ── Documents (SOUL.md, AGENTS.md, etc.) ─────────────────────────────
|
||||
documents = mkOption {
|
||||
type = types.attrsOf (types.either types.str types.path);
|
||||
default = { };
|
||||
description = ''
|
||||
Workspace document files. Keys are filenames, values are either
|
||||
inline strings or paths to files. These are symlinked into the
|
||||
workspace directory on activation.
|
||||
'';
|
||||
example = literalExpression ''
|
||||
{
|
||||
"SOUL.md" = '''
|
||||
# SOUL.md
|
||||
You are a helpful AI assistant.
|
||||
''';
|
||||
"AGENTS.md" = ./my-agents.md;
|
||||
"USER.md" = '''
|
||||
# USER.md
|
||||
Name: Fay
|
||||
''';
|
||||
}
|
||||
'';
|
||||
};
|
||||
|
||||
# ── Service behavior ─────────────────────────────────────────────────
|
||||
logPath = mkOption {
|
||||
type = types.str;
|
||||
default = "${cfg.stateDir}/logs/gateway.log";
|
||||
defaultText = literalExpression ''"''${cfg.stateDir}/logs/gateway.log"'';
|
||||
description = "Log file path.";
|
||||
};
|
||||
|
||||
extraArgs = mkOption {
|
||||
type = types.listOf types.str;
|
||||
default = [ ];
|
||||
description = "Extra command-line arguments for `hermes gateway`.";
|
||||
};
|
||||
|
||||
execStart = mkOption {
|
||||
type = types.nullOr types.str;
|
||||
default = null;
|
||||
description = "Override ExecStart command. If unset, runs: hermes gateway.";
|
||||
};
|
||||
|
||||
extraPackages = mkOption {
|
||||
type = types.listOf types.package;
|
||||
default = [ ];
|
||||
description = "Extra packages to make available on PATH.";
|
||||
};
|
||||
|
||||
restart = mkOption {
|
||||
type = types.str;
|
||||
default = "always";
|
||||
description = "systemd Restart= policy.";
|
||||
};
|
||||
|
||||
restartSec = mkOption {
|
||||
type = types.int;
|
||||
default = 5;
|
||||
description = "systemd RestartSec= value.";
|
||||
};
|
||||
|
||||
# ── MCP servers ──────────────────────────────────────────────────────
|
||||
mcpServers = mkOption {
|
||||
type = types.attrsOf (types.submodule {
|
||||
options = {
|
||||
command = mkOption { type = types.str; description = "MCP server command."; };
|
||||
args = mkOption { type = types.listOf types.str; default = [ ]; };
|
||||
env = mkOption { type = types.attrsOf types.str; default = { }; };
|
||||
timeout = mkOption { type = types.nullOr types.int; default = null; };
|
||||
};
|
||||
});
|
||||
default = { };
|
||||
description = "MCP server configurations (merged into config.mcp_servers).";
|
||||
};
|
||||
};
|
||||
|
||||
config = lib.mkIf cfg.enable {
|
||||
users.users.${cfg.user} = {
|
||||
isSystemUser = true;
|
||||
group = cfg.group;
|
||||
home = cfg.homeDir;
|
||||
createHome = true;
|
||||
description = "Hermes Agent service user";
|
||||
# ── Merge MCP servers into config ────────────────────────────────────
|
||||
services.hermes-agent.config = lib.mkIf (cfg.mcpServers != { }) {
|
||||
mcp_servers = lib.mapAttrs (_name: srv:
|
||||
{ inherit (srv) command args; }
|
||||
// lib.optionalAttrs (srv.env != { }) { inherit (srv) env; }
|
||||
// lib.optionalAttrs (srv.timeout != null) { inherit (srv) timeout; }
|
||||
) cfg.mcpServers;
|
||||
};
|
||||
|
||||
users.groups.${cfg.group} = { };
|
||||
# ── User / group ─────────────────────────────────────────────────────
|
||||
users.groups.${cfg.group} = lib.mkIf cfg.createUser { };
|
||||
users.users.${cfg.user} = lib.mkIf cfg.createUser {
|
||||
isSystemUser = true;
|
||||
group = cfg.group;
|
||||
home = cfg.stateDir;
|
||||
createHome = true;
|
||||
shell = pkgs.bashInteractive;
|
||||
};
|
||||
|
||||
systemd.services.hermes-agent = {
|
||||
# ── Directories ──────────────────────────────────────────────────────
|
||||
systemd.tmpfiles.rules = [
|
||||
"d ${cfg.stateDir} 0750 ${cfg.user} ${cfg.group} - -"
|
||||
"d ${cfg.stateDir}/.hermes 0750 ${cfg.user} ${cfg.group} - -"
|
||||
"d ${cfg.workingDirectory} 0750 ${cfg.user} ${cfg.group} - -"
|
||||
"d ${builtins.dirOf cfg.logPath} 0750 ${cfg.user} ${cfg.group} - -"
|
||||
];
|
||||
|
||||
# ── Activation: link config + documents into state dir ───────────────
|
||||
system.activationScripts."hermes-agent-setup" = lib.stringAfter [ "users" ] ''
|
||||
# Link config file
|
||||
install -o ${cfg.user} -g ${cfg.group} -m 0640 -D ${configFile} ${cfg.stateDir}/.hermes/cli-config.yaml
|
||||
|
||||
# Link documents into workspace
|
||||
${lib.concatStringsSep "\n" (lib.mapAttrsToList (name: _value: ''
|
||||
install -o ${cfg.user} -g ${cfg.group} -m 0644 ${documentDerivation}/${name} ${cfg.workingDirectory}/${name}
|
||||
'') cfg.documents)}
|
||||
'';
|
||||
|
||||
# ── systemd service ──────────────────────────────────────────────────
|
||||
systemd.services.${cfg.unitName} = {
|
||||
description = "Hermes Agent Gateway";
|
||||
wantedBy = [ "multi-user.target" ];
|
||||
after = [ "network-online.target" ];
|
||||
wants = [ "network-online.target" ];
|
||||
wantedBy = [ "multi-user.target" ];
|
||||
|
||||
environment = {
|
||||
HOME = cfg.homeDir;
|
||||
HERMES_HOME = "${cfg.homeDir}/.hermes";
|
||||
} // cfg.extraEnvironment;
|
||||
HOME = cfg.stateDir;
|
||||
HERMES_HOME = "${cfg.stateDir}/.hermes";
|
||||
MESSAGING_CWD = cfg.workingDirectory;
|
||||
};
|
||||
|
||||
serviceConfig = {
|
||||
Type = "simple";
|
||||
User = cfg.user;
|
||||
Group = cfg.group;
|
||||
WorkingDirectory = cfg.workDir;
|
||||
ExecStart = lib.concatStringsSep " " ([
|
||||
"${cfg.package}/bin/hermes"
|
||||
"gateway"
|
||||
] ++ cfg.extraArgs);
|
||||
Restart = "on-failure";
|
||||
RestartSec = 5;
|
||||
WorkingDirectory = cfg.workingDirectory;
|
||||
|
||||
EnvironmentFile =
|
||||
[ generatedEnvFile ]
|
||||
++ cfg.environmentFiles;
|
||||
|
||||
ExecStart =
|
||||
if cfg.execStart != null then cfg.execStart
|
||||
else lib.concatStringsSep " " ([
|
||||
"${cfg.package}/bin/hermes"
|
||||
"gateway"
|
||||
] ++ cfg.extraArgs);
|
||||
|
||||
Restart = cfg.restart;
|
||||
RestartSec = cfg.restartSec;
|
||||
|
||||
StandardOutput = "append:${cfg.logPath}";
|
||||
StandardError = "append:${cfg.logPath}";
|
||||
|
||||
# Hardening
|
||||
NoNewPrivileges = true;
|
||||
ProtectSystem = "strict";
|
||||
ProtectHome = false;
|
||||
ReadWritePaths = [ cfg.homeDir ];
|
||||
ReadWritePaths = [ cfg.stateDir ];
|
||||
PrivateTmp = true;
|
||||
} // lib.optionalAttrs (cfg.environmentFile != null) {
|
||||
EnvironmentFile = cfg.environmentFile;
|
||||
};
|
||||
|
||||
path = [ cfg.package ] ++ cfg.extraPackages;
|
||||
path = [
|
||||
cfg.package
|
||||
pkgs.bash
|
||||
pkgs.coreutils
|
||||
pkgs.git
|
||||
] ++ cfg.extraPackages;
|
||||
};
|
||||
};
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue