# Setup Hermes Agent — Dari Nol Sampai Siap Pakai

> Berdasarkan real setup di VPS: Ubuntu 24.04, Hermes v0.16.0, DeepSeek V4 Flash
> VPS: srv1716368 | RAM 3.8GB | Disk 48GB | 1 Core
> Doc owner: Imam Crespo | Last update: 23 Juni 2026

---

## Daftar Isi

1. [Prasyarat & Spesifikasi VPS](#1-prasyarat--spesifikasi-vps)
2. [Install Hermes](#2-install-hermes)
3. [Konfigurasi Awal](#3-konfigurasi-awal)
4. [Setup Model Provider (DeepSeek)](#4-setup-model-provider-deepseek)
5. [Setup Telegram Gateway](#5-setup-telegram-gateway)
6. [Setup Claude Code CLI](#6-setup-claude-code-cli)
7. [Setup Memory (Supermemory)](#7-setup-memory-supermemory)
8. [Setup Systemd Service (Auto-start)](#8-setup-systemd-service-auto-start)
9. [Setup Skills & Library](#9-setup-skills--library)
10. [Setup Cron Jobs](#10-setup-cron-jobs)
11. [Cek Status & Troubleshoot](#11-cek-status--troubleshoot)

---

## 1. Prasyarat & Spesifikasi VPS

### Minimum Requirements
- **OS**: Ubuntu 22.04 / 24.04 (recommended)
- **RAM**: minimal 2GB, makin besar makin baik (Hermes pakai ~1-3GB peak)
- **Disk**: minimal 20GB free
- **Python**: 3.11+ (auto di-handle installer)
- **Node.js**: 18+ (untuk Claude Code CLI)
- **Koneksi**: stabil, akses ke api.deepseek.com & api.telegram.org & github.com

### Spesifikasi VPS Ini
```
OS: Ubuntu 24.04.4 LTS (Noble)
Kernel: 6.8.0-124-generic x86_64
RAM: 3.8GB (1.6GB idle usage Hermes)
Disk: 48GB (21GB used)
Python: 3.12.3
Node: v22.22.3
```

---

## 2. Install Hermes

### 2.1 Install via Script Resmi

```bash
# Install Hermes Agent via bootstrap script
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```

Ini akan:
- Clone repo Hermes Agent ke `/usr/local/lib/hermes-agent/`
- Buat Python virtual environment (`venv`)
- Install dependencies Python
- Install Node.js dependencies (via npm)
- Set `hermes` binary ke `/usr/local/bin/hermes`
- Buat folder `~/.hermes/` sebagai home directory Hermes

### 2.2 Verifikasi Install

```bash
hermes --version
# Output: Hermes Agent v0.16.0 (2026.6.5) · upstream bb7ff7dc
# Project: /usr/local/lib/hermes-agent
# Python: 3.11.15
```

### 2.3 Update Hermes

```bash
# Cek update
hermes update
# Atau manual dari repo
cd /usr/local/lib/hermes-agent && git pull && pip install -e .
```

---

## 3. Konfigurasi Awal

### 3.1 Struktur Folder `~/.hermes/`

```
~/.hermes/
  ├── .env              # Environment variables (API keys, credentials)
  ├── config.yaml       # Main config Hermes
  ├── SOUL.md           # Operating constitution / personality
  ├── auth.json         # Provider auth tokens
  ├── skills/           # Skills installed
  ├── library/          # Domain library (manifest, index)
  ├── cron/             # Cron job definitions
  ├── profiles/         # Profiles (optional)
  ├── logs/             # Log files
  ├── cache/            # Cache directory
  └── node/bin/         # Node.js tools (Claude Code, dll)
```

### 3.2 Config File Dasar (`config.yaml`)

File utama konfigurasi ada di `~/.hermes/config.yaml`. Bagian critical yang harus diset:

```yaml
model:
  base_url: https://api.deepseek.com
  default: deepseek-v4-flash
  provider: deepseek

terminal:
  backend: local        # 'local' buat VPS langsung, 'docker' kalo mau container
  auto_source_bashrc: true

gateway:
  strict: false

display:
  language: id          # Bahasa Indonesia
  streaming: true       # Biar response real-time
```

---

## 4. Setup Model Provider (DeepSeek)

### 4.1 Set API Key

Edit `~/.hermes/.env`:

```env
# =========================
# HERMES MODEL PROVIDER
# =========================
DEEPSEEK_API_KEY="sk-deepseek-xxx-isi-dengan-api-key-mu"
```

### 4.2 Konfigurasi di `config.yaml`

```yaml
model:
  base_url: https://api.deepseek.com
  default: deepseek-v4-flash
  provider: deepseek
```

### 4.3 (Optional) Setup OpenRouter sebagai fallback

```env
OPENROUTER_API_KEY="sk-or-xxx-isi-dengan-api-key-mu"
```

Di `config.yaml`:
```yaml
auxiliary:
  vision:
    provider: openrouter
    model: nvidia/nemotron-nano-12b-v2-vl:free
```

### 4.4 Verifikasi Provider

```bash
hermes eval "Halo, siapa kamu?"       # Test call
hermes config show                     # Lihat config aktif
```

---

## 5. Setup Telegram Gateway

Gateway adalah jembatan antara Hermes dan platform messaging (Telegram).

### 5.1 Buat Bot Telegram

1. Buka Telegram, cari `@BotFather`
2. Kirim `/newbot`
3. Ikuti instruksi, dapatkan **Bot Token** (format: `882182xxxx:AAG-xxx`)
4. (Optional) Set profile pic, description, dsb

### 5.2 Set Environment Variables

Di `~/.hermes/.env`:

```env
# =========================
# TELEGRAM GATEWAY
# =========================
TELEGRAM_BOT_TOKEN="882182xxxx:AAG-xxx"
TELEGRAM_ALLOWED_USERS="262525466,7190011277"     # User ID yang boleh DM (dipisah koma)
TELEGRAM_GROUP_ALLOWED_USERS="1630193854"          # User ID yang cuma boleh di grup
TELEGRAM_HOME_CHANNEL="-5574954474"                # Chat ID grup/channel default
```

### 5.3 Konfigurasi di config.yaml

```yaml
telegram:
  reactions: true                                # Reaksi pesan (like/emoji)
  require_mention: false                         # Harus mention @botname?
  allowed_chats: ""                              # Whitelist chat ID (kosong = semua)
  channel_prompts: {}                            # Prompt per-channel tertentu
```

### 5.4 Cara dapat User ID & Chat ID

- **User ID**: kirim pesan ke `@userinfobot` di Telegram
- **Chat ID Grup**: buka grup di web.telegram.org, lihat URL `?g=xxx` atau pake bot
- **Group Thread ID**: dari topic ID dalam grup

### 5.5 Auth System Hermes

Hermes punya 3 layer auth untuk Telegram:

1. **`TELEGRAM_ALLOWED_USERS`** — user yang bisa chat via DM (global)
2. **`TELEGRAM_GROUP_ALLOWED_USERS`** — user yang cuma bisa di grup tertentu
3. **`TELEGRAM_GROUP_ALLOWED_CHATS`** — bypass user check, whitelist chat ID

Logic auth ada di `gateway/authz_mixin.py`:
```python
# Priority: env vars → pairing store → adapter policy
```

---

## 6. Setup Claude Code CLI

Digunakan untuk coding kompleks (Laravel/Filament) yang didelegasikan dari Hermes.

### 6.1 Install Node.js (kalo belum ada)

```bash
# Via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22

# Atau via apt (alternatif)
apt install nodejs npm
```

### 6.2 Install Claude Code

```bash
# Install di ~/.hermes/node/bin/
npm install -g @anthropic-ai/claude@latest --prefix ~/.hermes/node

# Set PATH
export PATH="$HOME/.hermes/node/bin:$PATH"
```

### 6.3 Verifikasi

```bash
~/.hermes/node/bin/claude --version
# Output: 2.1.181 (Claude Code)
```

### 6.4 Integrasi dengan Hermes

Pastikan PATH di `config.yaml` atau systemd service mengarah ke `~/.hermes/node/bin/`.

```yaml
# Di systemd service udah include:
# Environment="PATH=...:/root/.hermes/node/bin:..."
```

---

## 7. Setup Memory (Supermemory)

Hermes pake Supermemory sebagai long-term memory layer.

### 7.1 Daftar ke Supermemory

1. Buka https://supermemory.ai
2. Register, dapatkan **API Key** (format: `sm_xxx`)
3. Set di `~/.hermes/.env`:

```env
# =========================
# HERMES LONG-TERM MEMORY
# =========================
SUPERMEMORY_API_KEY="sm_8Kc...xxx"
```

### 7.2 Konfigurasi Memory di config.yaml

```yaml
memory:
  memory_enabled: true
  user_profile_enabled: true
  write_approval: false          # Auto-save memory, no approval needed
  memory_char_limit: 2200        # Max chars buat memory notes
  user_char_limit: 1375          # Max chars buat user profile
  flush_min_turns: 6             # Simpen memory setiap N turns
  nudge_interval: 10             # Ingatkan untuk simpen memory
```

### 7.3 Cara Pakai Memory

```bash
# Dari dalam sesi Hermes, memory otomatis tersimpan.
# Manual:
hermes memory --action add --target memory --content "User suka dark mode"
```

---

## 8. Setup Systemd Service (Auto-start)

Hermes Gateway harus jalan sebagai service supaya nyala otomatis setelah VPS restart.

### 8.1 File Service

Lokasi: `~/.config/systemd/user/hermes-gateway.service`

```ini
[Unit]
Description=Hermes Agent Gateway - Messaging Platform Integration
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0

[Service]
Type=simple
ExecStart=/usr/local/lib/hermes-agent/venv/bin/python -m hermes_cli.main gateway run
WorkingDirectory=/root/.hermes
Environment="PATH=/usr/local/lib/hermes-agent/venv/bin:/usr/local/lib/hermes-agent/node_modules/.bin:/root/.hermes/node/bin:/root/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
Environment="VIRTUAL_ENV=/usr/local/lib/hermes-agent/venv"
Environment="HERMES_HOME=/root/.hermes"
Restart=always
RestartSec=5
RestartForceExitStatus=75
KillMode=mixed
KillSignal=SIGTERM
ExecReload=/bin/kill -USR1 $MAINPID
TimeoutStopSec=210
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target
```

### 8.2 Enable & Start Service

```bash
# Reload systemd user daemon
systemctl --user daemon-reload

# Enable auto-start
systemctl --user enable hermes-gateway

# Start
systemctl --user start hermes-gateway

# Cek status
systemctl --user status hermes-gateway

# Lihat log real-time
journalctl --user -u hermes-gateway -f
```

### 8.3 Restart Gateway

```bash
# Cara 1: systemctl
systemctl --user restart hermes-gateway

# Cara 2: kill PID (auto-restart karena Restart=always)
kill <PID_GATEWAY>

# Cara 3: reload config tanpa restart
kill -USR1 <PID_GATEWAY>
```

### 8.4 Pastikan Lingkungan VPS Bisa Jalan

⚠️ **PENTING**: VPS di Hostinger / penyedia lain mungkin perlu ini:

```bash
# Aktifkan lingering biar user service jalan walau gak login
loginctl enable-linger root
```

---

## 9. Setup Skills & Library

Skills adalah procedural memory — resep untuk task berulang.

### 9.1 Skills yang Terinstall

Semua skills ada di folder `~/.hermes/skills/`:

```
apple/
autonomous-ai-agents/
  ├── coding-agents/         # Delegasi coding ke Claude Code
  └── hermes-agent/          # Setup & config Hermes
creative/
data-science/
devops/
  └── hermes-infra/          # Infra management
dogfood/
email/
github/                      # Github workflow, PR, review
marketing/
  ├── ngiklan/               # Meta Ads operations
  └── digitala-*             # Digitala-specific skills
media/
mlops/
note-taking/
productivity/
red-teaming/
research/
smart-home/
social-media/
software-development/
  ├── laravel-filament/      # Laravel + Filament patterns
  ├── debugging/             # Debug methodology
  ├── plan/                  # Planning mode
  └── spike/                 # Throwaway experiments
```

### 9.2 Load Skills

```bash
# Dari dalam sesi Hermes, skills auto-load via matching.
# Manual:
skill_view(name="laravel-filament")
```

### 9.3 Buat Skill Baru

```bash
# Skill akan dibuat di ~/.hermes/skills/<nama>/
# Via perintah: "simpen cara ini sebagai skill"
```

### 9.4 Library Structure

Folder `~/.hermes/library/`:

```
library/
  ├── INDEX.md              # Katalog semua domain & fitur
  ├── domains/              # Manifest per domain
  │   ├── DIGITALA.md       # Domain: Digitala SAAS
  │   ├── GINELA_ADS.md     # Domain: Meta Ads
  │   └── HERMES_INFRA.md   # Domain: Agent infra
  ├── skills/               # Skill inventory
  └── observability/        # Changelog, audit log
```

---

## 10. Setup Cron Jobs

Hermes punya cron system sendiri (bukan crontab) — lihat di `~/.hermes/cron/`.

### 10.1 Hermes Cron

```bash
# Lihat cron jobs
cronjob action=list

# Buat cron job baru
cronjob action=create \
  name="Nama Job" \
  schedule="0 9 * * *" \
  prompt="Lakukan sesuatu setiap jam 9 pagi"

# Hapus cron job
cronjob action=list   # ambil job_id
cronjob action=remove job_id=<id>
```

### 10.2 System Crontab (untuk non-Hermes script)

```bash
# Edit crontab
crontab -e
# Contoh entry yang ada di setup ini:
# 0 8 * * * /opt/marketing-ai-agent/scripts/run_analyze.sh
```

---

## 11. Cek Status & Troubleshoot

### 11.1 Status Gateway

```bash
# Cek service
systemctl --user status hermes-gateway

# Cek detail gateway state
cat ~/.hermes/gateway_state.json
# {
#   "pid": 1948546,
#   "kind": "hermes-gateway",
#   "gateway_state": "running",
#   "platforms": {
#     "telegram": {"state": "connected"}
#   }
# }
```

### 11.2 Cek Log

```bash
# Log gateway via journalctl
journalctl --user -u hermes-gateway -f --since "1 hour ago"

# Log Hermes session
tail -f ~/.hermes/logs/*.log

# Debug interrupt
cat ~/.hermes/interrupt_debug.log
```

### 11.3 Masalah Umum

| Masalah | Penyebab | Solusi |
|---------|----------|--------|
| Gateway gak connect Telegram | Token salah | Cek `TELEGRAM_BOT_TOKEN` di `.env` |
| "Flood control exceeded" | Terlalu banyak pesan per detik | Gateway handle otomatis, tunggu |
| Memory penuh | RAM 3.8GB terbatas | Monitor via `free -h`, kill process gak perlu |
| Claude Code error | PATH gak sampai | Cek `~/.hermes/node/bin/claude` ada |
| DeepSeek API error | API key expired | Renew key, update `.env`, restart gateway |
| Gateway crash-loop | Config error | Cek `journalctl -u hermes-gateway -n 50` |
| Skill gak terload | Skill corrupt/stale | `skill_manage action=patch` atau `action=delete` |

### 11.4 Restart Total

```bash
# Restart gateway
systemctl --user restart hermes-gateway

# Tunggu 10 detik, cek lagi
sleep 10
systemctl --user status hermes-gateway

# Cek connect
cat ~/.hermes/gateway_state.json | grep -E "state|platforms"
```

---

## Lampiran: File-file Penting

| File | Fungsi |
|------|--------|
| `~/.hermes/.env` | Semua API keys & credentials |
| `~/.hermes/config.yaml` | Konfigurasi utama Hermes |
| `~/.hermes/SOUL.md` | Operating constitution (personality, rules) |
| `~/.hermes/auth.json` | Provider auth tokens (auto-managed) |
| `~/.hermes/gateway_state.json` | Status gateway real-time |
| `~/.config/systemd/user/hermes-gateway.service` | Systemd unit |
| `~/.hermes/skills/` | Semua skills terinstall |
| `~/.hermes/library/` | Domain & fitur dokumentasi |
| `/usr/local/lib/hermes-agent/` | Source code Hermes |

## Lampiran: Cheatsheet Perintah

```bash
# Hermes CLI
hermes --version              # Cek versi
hermes update                 # Update Hermes
hermes eval "prompt"          # Test prompt langsung

# Gateway
systemctl --user start hermes-gateway
systemctl --user stop hermes-gateway
systemctl --user restart hermes-gateway
systemctl --user status hermes-gateway

# Logs
journalctl --user -u hermes-gateway -f

# Process
ps aux | grep hermes
kill <PID>
```