Hermes Repository Access and Persistence Policy

Summary

This policy defines the architectural approach for granting the Hermes agent read access to the local project repository on NixOS appliances. It establishes the use of directory traversal permissions and symlinks managed via NixOS activation scripts and tmpfiles rules to ensure access persists across system rebuilds without compromising file ownership.

Details

To enable the Hermes agent to provide context-aware assistance regarding the Sokrates codebase, the agent requires read access to the repository located at /home/hakon/sokrates/. Providing this access on a NixOS-managed system requires navigating the constraints of the nix-hermes module and the system’s immutable configuration patterns.

Access Mechanism

The primary method for granting access is through filesystem traversal and symlinking rather than changing the agent’s primary working directory.

1. Directory Traversal: The user home directory (e.g., /home/hakon) must have the executable bit set for others (chmod o+x) to allow the hermes service user to traverse into the directory and access the repository subfolder.
2. Symlink Integration: To avoid ownership conflicts, the Hermes agent’s workingDirectory remains at its default location. A symlink is created within the Hermes workspace pointing to the repository. This allows the agent to use its file-browsing tools to explore the codebase without the NixOS module attempting to claim ownership of the repository files (which would happen if the workingDirectory were set directly to the repo path).

Persistence and NixOS Integration

Because NixOS rebuilds can reset manual filesystem changes, the access configuration is codified in the system configuration:

• systemd.tmpfiles: The L (Link) rule in systemd.tmpfiles.rules is used to ensure the symlink from the Hermes workspace to the repository is recreated automatically on boot or during system activation.
• Activation Scripts: Specific logic is added to the nix-hermes module activation phase to ensure that the .env files and necessary directory permissions are maintained. This prevents the “locked home directory” issue where a rebuild might revert the o+x permission on the developer’s home directory.
• Ownership Constraints: The system is configured to prevent the hermes user from taking ownership of the repository. The repository remains owned by the primary developer (e.g., hakon:users), while Hermes is granted world-readable access.

Security Boundary

This configuration respects the Sokrates security boundary. While Hermes can read the repository to understand the codebase and assist in development, it does not have write access to the repository or access to customer-specific credentials stored in the intelligence secrets directory. The access is strictly limited to the filesystem level required for codebase context.

Related

• Hermes Agent
• NixOS Appliance Configuration
• Security Boundary and Credential Isolation
• nix-hermes Module