0xrsydn/nix-hermes-agent
1
mirror of https://github.com/0xrsydn/nix-hermes-agent.git synced 2026-08-07 00:53:52 +00:00
Code Issues Projects Releases Packages Wiki Activity
nix-hermes-agent/docs/CONFIG-MAP.md
Ciphercat 010a1b6644 feat: bump hermes-agent 0.2.0 → 0.3.0 + auto-update CI 
- Update package.nix to v0.3.0 (NousResearch/hermes-agent v2026.3.17)
- Add scripts/update-pins.sh — checks latest stable release, prefetches, validates build
- Add .github/workflows/update-pins.yml — runs every 6h + manual dispatch
- Pattern follows nix-openclaw's yolo-update approach
2026-03-17 19:10:01 +00:00

335 lines
12 KiB
Markdown
Raw Permalink Blame History

# Hermes Agent Configuration Map
**Source:** `hermes_cli/config.py` + `gateway/config.py` (v0.2.0)
Everything below can be set declaratively via the NixOS module's `services.hermes-agent.config` option (rendered as `cli-config.yaml`), `environmentFiles` (secrets), or `environment` (non-secret env vars).
---
## 1. Model & Provider
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `model` | string | `"anthropic/claude-opus-4.6"` | Default model (`provider/model` format) |
| `toolsets` | list | `["hermes-cli"]` | Enabled toolsets (e.g. `["all"]`, `["hermes-cli", "browser"]`) |
**Auth providers** (resolved automatically based on env vars / OAuth):
- Nous Portal (OAuth) → `hermes login --provider nous`
- OpenAI Codex (OAuth) → `hermes login --provider openai-codex`
- OpenRouter → `OPENROUTER_API_KEY`
- Z.AI / GLM → `GLM_API_KEY` / `ZAI_API_KEY`
- Kimi → `KIMI_API_KEY`
- MiniMax → `MINIMAX_API_KEY`
- Anthropic → `ANTHROPIC_API_KEY` or Claude Code OAuth
---
## 2. Agent Behavior
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `agent.max_turns` | int | `90` | Max tool-calling iterations per conversation |
---
## 3. Terminal / Sandbox
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `terminal.backend` | string | `"local"` | `local` / `docker` / `singularity` / `modal` / `daytona` / `ssh` |
| `terminal.cwd` | string | `"."` | Working directory for commands |
| `terminal.timeout` | int | `180` | Command timeout (seconds) |
| `terminal.docker_image` | string | `"nikolaik/python-nodejs:..."` | Docker image |
| `terminal.singularity_image` | string | ... | Singularity image |
| `terminal.modal_image` | string | ... | Modal image |
| `terminal.daytona_image` | string | ... | Daytona image |
| `terminal.container_cpu` | int | `1` | Container CPU limit |
| `terminal.container_memory` | int | `5120` | Container memory (MB) |
| `terminal.container_disk` | int | `51200` | Container disk (MB) |
| `terminal.container_persistent` | bool | `true` | Persist filesystem across sessions |
| `terminal.docker_volumes` | list | `[]` | Docker volume mounts (`host:container`) |
**SSH backend env vars:**
- `TERMINAL_SSH_HOST`, `TERMINAL_SSH_USER`, `TERMINAL_SSH_KEY`
---
## 4. Context Compression
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `compression.enabled` | bool | `true` | Auto-compress long conversations |
| `compression.threshold` | float | `0.50` | Context usage % to trigger compression |
| `compression.summary_model` | string | `"google/gemini-3-flash-preview"` | Model for summaries |
| `compression.summary_provider` | string | `"auto"` | Provider for compression model |
---
## 5. Auxiliary Models
Side-task models (vision, web extraction, etc). Each has the same schema:
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `auxiliary.<task>.provider` | string | `"auto"` | Provider override |
| `auxiliary.<task>.model` | string | `""` | Model override |
| `auxiliary.<task>.base_url` | string | `""` | Direct endpoint URL |
| `auxiliary.<task>.api_key` | string | `""` | API key for endpoint |
**Tasks:** `vision`, `web_extract`, `compression`, `session_search`, `skills_hub`, `mcp`, `flush_memories`
---
## 6. Delegation (Subagents)
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `delegation.model` | string | `""` | Model for subagents (empty = inherit parent) |
| `delegation.provider` | string | `""` | Provider for subagents |
| `delegation.base_url` | string | `""` | Direct endpoint for subagents |
| `delegation.api_key` | string | `""` | API key for delegation endpoint |
---
## 7. Display
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `display.compact` | bool | `false` | Compact output mode |
| `display.personality` | string | `"kawaii"` | UI personality |
| `display.resume_display` | string | `"full"` | Session resume display |
| `display.bell_on_complete` | bool | `false` | Bell sound on completion |
| `display.show_reasoning` | bool | `false` | Show model reasoning |
| `display.skin` | string | `"default"` | UI skin |
---
## 8. Memory
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `memory.memory_enabled` | bool | `true` | Persistent curated memory |
| `memory.user_profile_enabled` | bool | `true` | User profile memory |
| `memory.memory_char_limit` | int | `2200` | Max chars for memory context |
| `memory.user_char_limit` | int | `1375` | Max chars for user profile |
---
## 9. Browser
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `browser.inactivity_timeout` | int | `120` | Browser auto-close (seconds) |
| `browser.record_sessions` | bool | `false` | Record browser sessions as WebM |
---
## 10. Checkpoints (Filesystem Snapshots)
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `checkpoints.enabled` | bool | `false` | Auto-snapshot before destructive ops |
| `checkpoints.max_snapshots` | int | `50` | Max checkpoints per directory |
---
## 11. TTS (Text-to-Speech)
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `tts.provider` | string | `"edge"` | `edge` (free) / `elevenlabs` (premium) / `openai` |
| `tts.edge.voice` | string | `"en-US-AriaNeural"` | Edge TTS voice |
| `tts.elevenlabs.voice_id` | string | `"pNInz6obpgDQGcFmaJgB"` | ElevenLabs voice ID |
| `tts.elevenlabs.model_id` | string | `"eleven_multilingual_v2"` | ElevenLabs model |
| `tts.openai.model` | string | `"gpt-4o-mini-tts"` | OpenAI TTS model |
| `tts.openai.voice` | string | `"alloy"` | OpenAI TTS voice |
---
## 12. STT (Speech-to-Text)
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `stt.enabled` | bool | `true` | Enable voice transcription |
| `stt.provider` | string | `"local"` | `local` (faster-whisper) / `groq` / `openai` |
| `stt.local.model` | string | `"base"` | Local model size: tiny/base/small/medium/large-v3 |
| `stt.openai.model` | string | `"whisper-1"` | OpenAI STT model |
---
## 13. Voice (Interactive)
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `voice.record_key` | string | `"ctrl+b"` | Push-to-talk key |
| `voice.max_recording_seconds` | int | `120` | Max recording length |
| `voice.auto_tts` | bool | `false` | Auto-speak responses |
| `voice.silence_threshold` | int | `200` | RMS silence threshold |
| `voice.silence_duration` | float | `3.0` | Seconds of silence → auto-stop |
---
## 14. Human Delay (Anti-Detection)
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `human_delay.mode` | string | `"off"` | `off` / `on` / `adaptive` |
| `human_delay.min_ms` | int | `800` | Min delay (ms) |
| `human_delay.max_ms` | int | `2500` | Max delay (ms) |
---
## 15. Security
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `security.redact_secrets` | bool | `true` | Redact API keys from tool output |
| `security.tirith_enabled` | bool | `true` | Pre-exec scanning via tirith |
| `security.tirith_path` | string | `"tirith"` | Path to tirith binary |
| `security.tirith_timeout` | int | `5` | Tirith scan timeout (seconds) |
| `security.tirith_fail_open` | bool | `true` | Allow exec if tirith fails |
---
## 16. Discord
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `discord.require_mention` | bool | `true` | Require @mention to respond in channels |
| `discord.free_response_channels` | string | `""` | Comma-separated channel IDs for free response |
| `discord.auto_thread` | bool | `true` | Auto-create threads on @mention |
---
## 17. Session Reset Policy
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `session_reset.mode` | string | `"both"` | `daily` / `idle` / `both` / `none` |
| `session_reset.at_hour` | int | `4` | Daily reset hour (0-23, local time) |
| `session_reset.idle_minutes` | int | `1440` | Idle timeout before reset (minutes) |
---
## 18. Miscellaneous
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `timezone` | string | `""` | IANA timezone (empty = server-local) |
| `command_allowlist` | list | `[]` | Permanently allowed dangerous commands |
| `quick_commands` | dict | `{}` | User-defined slash commands (exec type) |
| `personalities` | dict | `{}` | Custom personality prompts |
| `prefill_messages_file` | string | `""` | Path to JSON prefill messages |
| `honcho` | dict | `{}` | Honcho AI-native memory overrides |
---
## 19. MCP Servers
Defined via `services.hermes-agent.mcpServers` in the NixOS module:
```nix
mcpServers = {
my-server = {
command = "npx";
args = [ "-y" "my-mcp-server" ];
env = { API_KEY = "..."; };
timeout = 30;
};
};
```
Merged into `config.mcp_servers` in the rendered YAML.
---
## 20. Fallback Model (Failover)
Not in defaults — must be explicitly configured:
```yaml
fallback_model:
provider: openrouter # openrouter | nous | openai-codex | zai | kimi-coding | minimax
model: anthropic/claude-sonnet-4
# Optional for custom endpoints:
# base_url: "http://..."
# api_key_env: "MY_CUSTOM_KEY"
```
Triggers on: 429 (rate limit), 529 (overload), 503 (service error), connection failures.
---
## 21. Environment Variables (Secrets via `environmentFiles`)
### Provider Keys
| Variable | Provider |
|----------|----------|
| `OPENROUTER_API_KEY` | OpenRouter (default fallback) |
| `GLM_API_KEY` / `ZAI_API_KEY` | Z.AI / GLM |
| `KIMI_API_KEY` | Kimi / Moonshot |
| `MINIMAX_API_KEY` | MiniMax (international) |
| `MINIMAX_CN_API_KEY` | MiniMax (China) |
| `ANTHROPIC_API_KEY` | Anthropic direct |
| `ANTHROPIC_TOKEN` | Anthropic OAuth/setup token |
### Tool Keys
| Variable | Tool |
|----------|------|
| `FIRECRAWL_API_KEY` | Web search/scraping |
| `BROWSERBASE_API_KEY` | Cloud browser |
| `FAL_KEY` | Image generation |
| `ELEVENLABS_API_KEY` | Premium TTS |
| `VOICE_TOOLS_OPENAI_KEY` | Whisper STT + OpenAI TTS |
| `GITHUB_TOKEN` | Skills Hub |
| `HONCHO_API_KEY` | AI-native memory |
| `TINKER_API_KEY` | RL training |
| `WANDB_API_KEY` | Experiment tracking |
### Messaging Tokens
| Variable | Platform |
|----------|----------|
| `TELEGRAM_BOT_TOKEN` | Telegram |
| `TELEGRAM_ALLOWED_USERS` | Telegram user whitelist |
| `DISCORD_BOT_TOKEN` | Discord |
| `DISCORD_ALLOWED_USERS` | Discord user whitelist |
| `SLACK_BOT_TOKEN` | Slack |
| `SLACK_APP_TOKEN` | Slack (Socket Mode) |
| `SIGNAL_HTTP_URL` | Signal |
| `SIGNAL_ACCOUNT` | Signal |
| `HASS_TOKEN` | Home Assistant |
| `EMAIL_ADDRESS` / `EMAIL_PASSWORD` / `EMAIL_IMAP_HOST` / `EMAIL_SMTP_HOST` | Email |
| `GATEWAY_ALLOW_ALL_USERS` | Allow all users (global) |
### Agent Settings
| Variable | Description |
|----------|-------------|
| `MESSAGING_CWD` | Working directory for messaging |
| `SUDO_PASSWORD` | Sudo password for terminal |
| `HERMES_MAX_ITERATIONS` | Max iterations override |
---
## 22. Custom Providers (config.yaml)
```yaml
custom_providers:
- name: "local-vllm"
base_url: "http://localhost:8000/v1"
api_key: "" # optional
```
Use with: `hermes chat --provider custom:local-vllm`
---
## Summary: What Goes Where
| What | Where | NixOS Module Option |
|------|-------|---------------------|
| Model, toolsets, display, terminal, etc. | `cli-config.yaml` | `config = { ... }` |
| API keys, tokens, passwords | `.env` / env vars | `environmentFiles = [ "/run/secrets/hermes.env" ]` |
| OAuth tokens (Nous, Codex) | `auth.json` | Runtime via `hermes login` (persistent) |
| MCP servers | `cli-config.yaml` | `mcpServers = { ... }` |
| SOUL.md, AGENTS.md, USER.md | Workspace files | `documents = { ... }` |
| Gateway platform config | env vars or `gateway.json` | `environmentFiles` |
Reference in a new issue View git blame Copy permalink