---
created: 2026-05-26 21:13
modified: 2026-05-26 21:13
type: note
tags:
  - ai
  - dev
  - dev-ops
  - agents
aliases: []
---
# [[Hermes Ai autonomous Agent]]

# Hermes Agent — Local Setup Overview

## What is it?

- **Open-source autonomous AI agent** by Nous Research (MIT license, ~150K GitHub stars)
- Runs **on your own hardware** — not a cloud service
- You talk to it via **Telegram, Discord, Slack, terminal TUI, or web dashboard**
- **Self-improving** — saves workflows as reusable "skills" (markdown files) you can read and edit
- Integrates with: Gmail, Google Calendar, Home Assistant, Obsidian, email, browser automation, cron scheduling

---

## What I can use it for

### Daily personal
- Morning briefings (email + calendar + tasks → Telegram)
- Email triage and draft responses
- Calendar management via chat
- Home Assistant control (lights, climate, sensors, automations)
- Task tracking (Todoist, Obsidian tasks)

### Scheduled automations (cron)
- Daily/weekly research summaries
- Server monitoring (logs, disk, uptime) with alerts
- Backup reminders and health checks
- Regular file cleanup and organization

### DevOps & infrastructure
- Remote server management via SSH
- Log review and anomaly detection
- Automated reports delivered to messaging apps

### Information
- Web research and synthesis
- Obsidian vault search and management
- Multi-source summarization

---

## My setup

### Machines
- **.27** — Desktop/dev machine, turns off most nights
- **.13** — Stays on 24/7 (server/NAS)

### Architecture decision
- Run Hermes on **.13** (always-on) as the **primary instance**
  - This is where cron jobs, scheduled tasks, and the gateway live
  - It's running 24/7 so automations fire reliably
- Access from **.27** and other machines via:
  - **Telegram** (phone, any machine)
  - **Web dashboard** (`http://[.13-ip]:9119`)
  - **Terminal TUI** via SSH into .13
- If .13 has low RAM: use **cloud model API** (OpenRouter free tier, Anthropic API) instead of local model
- If .13 has 8GB+ RAM: can run **8B local models** via Ollama for privacy

### Model options
| Approach | Cost | Privacy | Speed | Requirements |
|---|---|---|---|---|
| OpenRouter free tier | $0 | Medium | Fast | Internet |
| OpenRouter paid | ~$5-10/mo | Medium | Fast | Internet |
| Anthropic API (Claude) | ~$5-15/mo | Low | Fast | Internet |
| Local model via Ollama | $0 (hardware) | **High** | 2-10 t/s on CPU | 8GB+ RAM, 4+ cores |
| Local model + GPU | $0 (hardware) | **High** | 30-100+ t/s | NVIDIA GPU with 8GB+ VRAM |

---

## Installation — NixOS Container Mode (Method 3)

**Why container mode:**
- `NoNewPrivileges`, `ProtectSystem=strict`, `PrivateTmp` — systemd hardening
- Agent runs in Ubuntu container, **can't touch host filesystem** unless you mount volumes
- Can install packages inside container via `apt`/`pip`/`npm`
- Declarative in `configuration.nix` — reproducible

**NixOS config (.13):**
```nix
services.hermes-agent = {
  enable = true;
  container.enable = true;
  # environmentFile for secrets (sops-nix or agenix recommended)
};
```

**Three integration levels (pick one):**

| Level | Use case | Config location |
|---|---|---|
| `nix run` / `nix profile install` | Quick try, any Nix user | `~/.hermes/` |
| **NixOS module (native)** | Standard deployment, highest security | `configuration.nix` |
| **NixOS module (container)** | **Chosen method** — isolation + flexibility | `configuration.nix` |

---

## Security & access control

- **Dedicated `hermes` user** — can't access your files
- **Container isolation** — commands run inside Docker container, not host
- **Secrets via sops-nix/agenix** — API keys not stored in plain text
- **Sandbox terminal backend** — optional Docker per-command isolation
- **Credential files** mounted read-only into container only when needed
- Hermes has **no built-in sandbox** — the NixOS container mode is what provides this

### Filesystem access
- Hermes only sees what you explicitly give it
- Mount specific folders read-only if needed for a skill/project
- Without explicit mounts, container has zero host access

---

## Credentials & secrets

- API keys → `~/.hermes/.env` (or sops-nix/agenix on NixOS)
- Google OAuth (Gmail/Calendar/Drive) — interactive setup via `hermes model`, stores `google_token.json` and `google_secret.json`
- Home Assistant → Long-Lived Access Token in `.env` as `HASS_TOKEN`
- Telegram bot → Bot token in `.env`

---

## Workflow management

### Create automations
- **Plain English** — "every day at 9am, check my email and summarize"
- **CLI** — `hermes cron create "every 1d at 09:00" "Summarize overnight emails"`
- **From chat** — `/cron list`, `/cron pause <id>`, `/cron run <id>`

### Review existing workflows
- `hermes cron list` — all scheduled jobs
- `~/.hermes/cron/jobs.json` — job definitions
- `~/.hermes/cron/output/` — output from each run

### Skills (workflows as .md files)
- **`~/.hermes/skills/`** — all skills live here
- Agent **creates skills from your conversations** automatically
- 118 bundled skills out of the box (GitHub, Google Workspace, Obsidian, etc.)
- 500+ community skills in the [Skills Hub](https://hermes-agent.nousresearch.com)
- Each skill is a readable `SKILL.md` file — you can review, edit, delete

---

## Key paths (on .13)

```
~/.hermes/
├── config.yaml          # Main configuration
├── .env                 # API keys and secrets (or sops-nix)
├── SOUL.md              # Agent personality/identity
├── skills/              # All skills (bundled, hub, agent-created)
│   ├── devops/
│   ├── productivity/
│   ├── .hub/            # Skills Hub state
│   └── .bundled_manifest
├── cron/
│   ├── jobs.json        # Scheduled automations
│   └── output/          # Cron run outputs
├── sessions/            # Chat session history
├── state.db             # SQLite database (full-text search)
└── logs/                # agent.log, gateway.log, errors.log
```

---

## First steps after install

1. Run `hermes setup` — configure model provider
2. Add Telegram bot token to `.env` and run `hermes gateway`
3. Set up Google Workspace skill for email/calendar
4. Add Home Assistant token for smart home control
5. Set your first cron job: "every day at 9am, send me a briefing"
6. Create `AGENTS.md` in project folders for per-project instructions
7. Review what the agent has learned: check `~/.hermes/skills/` regularly