Sókrates Wiki

Environment Variable and Hermes Configuration Standards

3 min read

Environment Variable and Hermes Configuration Standards

Summary

This page outlines the architectural constraints and mandatory patterns for managing environment variables and Hermes Agent configurations within the Sokrates NixOS environment. It specifically addresses the prevention of environment clobbering and defines the unique model routing requirements for the Hermes service.

Details

The Sokrates project enforces specific standards for managing environment variables and agent configurations to ensure stability across NixOS deployments (sokrates-dev and sokrates-box). These rules are designed to navigate the constraints of NixOS service management and the security boundaries between the Hermes Agent and the Eidos knowledge graph.

Environment Variable Management

A critical architectural constraint, documented as the “environment variable gotcha,” exists where standard NixOS modules may clobber the .env file during service initialization. To maintain system integrity and ensure variables are correctly loaded, the following rules apply:

  • Prohibited Methods: Developers must not use symlinks for environment files or rely solely on the EnvironmentFile directive for dynamic secrets, as these are prone to being overwritten or ignored during nix-shell or systemd service transitions.
  • Prescribed Method: To add or update environment variables safely, the system utilizes ExecStartPre to append variables to the environment before the main service process executes. This ensures that the runtime environment is correctly populated without being destroyed by the Nix build process.

Hermes Agent Configuration

The Hermes Agent (the channel I/O agent) has specific configuration requirements that differ from the core Eidos API:

  • Model Routing: Unlike other components that may use LiteLLM for model abstraction, Hermes utilizes its own internal provider system. A key convention in this system is the use of the :free suffix for model strings to trigger specific routing logic.
  • Secrets Isolation: While Hermes manages channel credentials (Telegram, WhatsApp, etc.), it is strictly forbidden from accessing customer system credentials. All customer-facing secrets must reside in the intelligence secrets directory, accessible only to Eidos containers. This is a hard security boundary enforced by nftables.
  • Plugin System: Hermes operates a plugin system with specific permission sets. Adding new functionality requires registering the plugin within the agents/ package and ensuring it adheres to the defined permission model.

Workspace and Deployment

The project workspace layout must include the agents/ package to house Hermes-related logic. When deploying to a physical “box” (the CWWK N305 appliances), new secrets must be added directly to the designated secrets directory on the host to ensure they are picked up by the NixOS systemd services. These standards are codified in the project’s CLAUDE.md to ensure consistent developer behavior.

Graph View

Backlinks