Skip to content

README.md

Latest commit

 

History

History
239 lines (172 loc) · 6.12 KB

README.md

File metadata and controls

239 lines (172 loc) · 6.12 KB
Raw

Hermes Agent Charm

Test CharmHub License: MIT

Deploy Hermes Agent, the self-improving AI agent by Nous Research, with a single command using Juju.

CharmHub • Hermes Docs • Report Bug

Features

  • 🧠 Self-Improving: Built-in learning loop — creates skills from experience
  • 💬 Multi-Platform: 20+ messaging channels (Telegram, Discord, Slack, WhatsApp, Signal, LINE...)
  • 🤖 Multi-Provider: Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, Ollama, and more
  • ⚡ Production-Ready: Systemd service with automatic restarts
  • 📅 Scheduled Automations: Built-in cron with natural language
  • 🔒 Self-Hosted: Your data stays on your infrastructure

Quick Start

# Deploy Hermes Agent
juju deploy hermes --channel edge

# Configure with your AI provider
juju config hermes \
  ai-provider="anthropic" \
  ai-api-key="sk-ant-xxx" \
  ai-model="claude-sonnet-4"

# Wait for deployment
juju status --watch 1s

# Check status
juju run hermes/0 get-status format=json

Interactive Chat (TUI)

Via SSH (recommended for interactive use)

# Modern TUI (full terminal UI with panels)
juju ssh hermes/leader -- sudo -u ubuntu hermes chat --tui

# Classic REPL (simple text chat)
juju ssh hermes/leader -- sudo -u ubuntu hermes chat

# Single query (non-interactive)
juju ssh hermes/leader -- sudo -u ubuntu hermes chat -q "What is the weather?"

Via Web Dashboard

The dashboard (port 9119) includes an embedded Chat tab. Enable it by setting credentials:

juju config hermes dashboard-username=admin dashboard-password=<strong-password>

Access it at http://<unit-ip>:9119. The dashboard is disabled when credentials are not set.

Tips

  • Use --model provider/model to override the configured model for a session
  • Use --resume <session-id> to continue a previous conversation
  • Use --continue to resume the most recent session

AI Provider Configuration

Anthropic Claude (Recommended)

juju config hermes \
  ai-provider="anthropic" \
  ai-api-key="sk-ant-xxx" \
  ai-model="claude-sonnet-4"

OpenAI

juju config hermes \
  ai-provider="openai" \
  ai-api-key="sk-xxx" \
  ai-model="gpt-4"

Google Gemini

juju config hermes \
  ai-provider="google" \
  ai-api-key="YOUR-GEMINI-KEY" \
  ai-model="gemini-2.5-pro"

GitHub Copilot

juju config hermes \
  ai-provider="copilot" \
  ai-api-key="ghu_xxx" \
  ai-model="claude-sonnet-4"

Local Models (Ollama)

juju config hermes \
  ai-provider="ollama" \
  ai-model="llama3"

Messaging Platforms

# Telegram
juju config hermes telegram-bot-token="123456:ABC..."

# Discord
juju config hermes discord-bot-token="MTIz..."

# Slack
juju config hermes hermes \
  slack-bot-token="xoxb-..." \
  slack-app-token="xapp-..."
# LINE
juju config hermes \
  line-channel-access-token="..." \
  line-channel-secret="..."

Actions

Get Status

# Human-readable status
juju run hermes/0 get-status

# Structured JSON
juju run hermes/0 get-status format=json

Get Dashboard URL

Start the web-based management dashboard:

juju run hermes/0 get-dashboard-url

Note: Dashboard binds to 0.0.0.0:9119 when credentials are configured. Without credentials set, the dashboard does not start.

Secure remote access via Tailscale

Add tailscale to install-pkgs and expose the dashboard over your Tailscale network:

juju config hermes install-pkgs=tailscale
juju ssh hermes/0 -- sudo tailscale up
juju ssh hermes/0 -- tailscale serve --bg http://0.0.0.0:9119

The dashboard will then be reachable at https://<hostname>.<tailnet>.ts.net with TLS managed by Tailscale.

Backup

juju run hermes/0 backup
juju run hermes/0 backup output-path=/home/ubuntu/backups

List Models

juju run hermes/0 list-models
juju run hermes/0 list-models format=text

Pairing List

Show pending and approved DM users:

juju run hermes/0 pairing-list

Configuration Options

Option Type Default Description
ai-provider string AI provider (copilot, anthropic, openai, google, etc.)
ai-model string AI model name(s), comma-separated for fallback
ai-api-key string Provider API key
gateway-port int 3000 Gateway port (for future webhook use)
install-method string script Install method: script (recommended), git, or pip (deprecated)
version string latest Hermes version (PyPI version or git ref)
auto-update boolean false Auto-update on upgrade-charm
telegram-bot-token string Telegram bot token
discord-bot-token string Discord bot token
slack-bot-token string Slack bot token (xoxb-)
slack-app-token string Slack app token (xapp-)
dm-policy string pairing DM policy: pairing/open/closed
manual boolean false Manual config mode (skip auto-generation)
log-level string info Log level (debug/info/warn/error)
install-pkgs string Extra packages: chrome, chromium, firefox, tailscale, homebrew

Multi-model support: up to 10 additional AI slots (ai0 through ai9), each with -provider, -model, -api-key, -base-url.

See juju config hermes for the full list.

Requirements

  • Juju controller (version 3.1+)
  • Ubuntu Noble 24.04
  • API key for your chosen AI provider (except Ollama)

Development

# Validate charm structure
./validate.sh

# Pack the charm
charmcraft pack

# Deploy locally for testing
juju deploy ./hermes_amd64.charm --to lxd

License

MIT