hermes-speckl — Nix flake for Speckl SME Agent

A pre-configured Hermes Agent instance purpose-built for the Speckl specification language ecosystem.

What this gives you

One nixos-rebuild switch and you have a self-learning AI agent that:

• Understands SpeckDL, the Dark Provenance model, and your compiler architecture
• Compounds expertise across every Speckl task (code review, spec writing, research)
• Runs as a hardened systemd service with declarative config
• Connects via Discord, Telegram, Slack, WhatsApp, or CLI
• Gets faster on recurring tasks the longer it runs

Usage

Add to your system flake:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hermes-speckl.url = "github:sscoble/hermes-speckl";
  };

  outputs = { nixpkgs, hermes-speckl, ... }: {
    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        hermes-speckl.nixosModules.speckl
        ./configuration.nix
      ];
    };
  };
}

Then configure:

# configuration.nix
{ config, ... }: {
  services.hermes-speckl = {
    enable = true;

    # Declarative config (deep-merged into cli-config.yaml)
    settings = {
      model.default = "anthropic/claude-opus-4.6";
      toolsets = [ "all" ];
    };

    # LLM API keys (use sops-nix or agenix)
    environmentFiles = [ config.sops.secrets."hermes-env".path ];
  };
}

Apply:

nixos-rebuild switch --flake .#your-host
systemctl status hermes-speckl
journalctl -u hermes-speckl -f

What's pre-configured

Setting	Value
Model	anthropic/claude-opus-4.6 (override via settings.model.default)
Memory	Enabled with skill generation + user modeling
Terminal	Local backend, 180s timeout
Context compression	On, 85% threshold, Gemini 3 Flash summarizer
Agent	60 max turns, medium reasoning effort
Container mode	Enabled (agent can install packages for self-modification)
SOUL.md	Speckl domain expert persona (see documents/SOUL.md)

Container mode

The agent runs inside a persistent Ubuntu container with:

• Node 22 via NodeSource (for MCP servers, js tooling)
• Python 3.12 venv via uv (for pip installs, custom tools)
• Writable Nix store (bind-mounted from host)
• Sudo access for the agent user (self-modification)

This means the agent can npm i -g, pip install, and modify its own environment — essential for skill creation and tool discovery.

Development

# Run directly
nix run github:sscoble/hermes-speckl -- setup

# Or from a local clone
git clone https://os.scoble.me/forgejo/sscoble/hermes-speckl
cd hermes-speckl
nix build
./result/bin/hermes setup