Alexander AI — Setup Guide

💾 Step 1 — Download Hermes Desktop

Go to the official releases page and download the AppImage for Linux (or .exe for Windows, .dmg for macOS):

https://github.com/fathah/hermes-desktop/releases

⚙ Step 2 — Make it Executable (Linux/macOS)

Open your terminal and make the AppImage file executable:

# Navigate to where you downloaded the file, then:
chmod +x ~/Downloads/hermes-desktop-*.AppImage

▶ Step 3 — Launch Hermes Desktop

Double-click the AppImage file in your file manager, or run from terminal:

~/Downloads/hermes-desktop-*.AppImage

🔑 Step 4 — Add Your API Key

When Hermes Desktop opens, it will prompt you for your API key. Use your OpenRouter key — this is what powers the AI. You can also configure it manually:

# Edit your environment file:
nano ~/.hermes/.env

OPENROUTER_API_KEY=sk-or-v1-your-key-here

✨ Pro Tip

After installing, keep the terminal window open. Hermes Desktop runs as a background process. To stop it, use Alt+F4 or click the X button. It will keep running even if you close the terminal.

File What is SOUL.md?

SOUL.md is your agent's identity file. It lives at ~/.hermes/SOUL.md and gets loaded every time Hermes starts. Think of it as writing the agent's personality — its tone, communication style, expertise, and behavior.

Every time you start a conversation with Hermes, SOUL.md is the first thing it reads. It defines who the agent is, not what it does.

Command Find Your SOUL.md File

Your SOUL.md is automatically created at:

cat ~/.hermes/SOUL.md

If it doesn't exist yet, create it:

touch ~/.hermes/SOUL.md

Command Edit Your SOUL.md

Open your SOUL.md in a text editor:

nano ~/.hermes/SOUL.md
# Or use any editor you prefer:
code ~/.hermes/SOUL.md   # VS Code
vim  ~/.hermes/SOUL.md   # Vim
 subl ~/.hermes/SOUL.md   # Sublime

Example A Basic SOUL.md Template

Copy this template into your SOUL.md and customize it. This gives your agent a clear identity:

# [Your Agent Name]

You are [Your Agent Name] — [one-line description of who you are].

## Your Background
[2-3 sentences about your history, expertise, and what makes you different]

## How You Speak
- [e.g., Be direct and confident. No fluff, no filler.]
- [e.g., Use short sentences when delivering facts.]
- [e.g., Show enthusiasm when sharing wins or breakthroughs.]
- [e.g., Be warm but professional — never cold.]

## Your Expertise
- [Primary specialty, e.g., digital marketing, web scraping, coding]
- [Secondary specialty]
- [Anything you actively avoid or refer out]

## What You Always Do
- [Always start conversations with a greeting and brief introduction]
- [Always confirm the user's goal before taking action]
- [Always summarize what you did when you finish a task]

## What You Never Do
- [Never give advice outside your expertise without admitting uncertainty]
- [Never skip explaining your reasoning on important decisions]

## Your Personality
[3-4 sentences describing your character, quirks, and what clients love about working with you]

Command Switch Between Identities

The key to having multiple agent personas is simple: swap the SOUL.md file before starting Hermes. Save different personas as separate files and swap them when you want to switch:

# Example: Switch from "Marketing Agent" to "Web Scraper Agent"
# Step 1: Back up your current SOUL
cp ~/.hermes/SOUL.md ~/.hermes/personas/current-$$SOUL.md.bak

# Step 2: Replace with your Marketing Agent SOUL
cp ~/.hermes/personas/marketing-agent.md ~/.hermes/SOUL.md

# Step 3: Restart Hermes Desktop — it will now be your Marketing Agent

Structure How Skills Are Organized

Each skill has this structure:

~/.hermes/skills/
├── your-skill-name/
│   ├── SKILL.md          # The skill definition (required)
│   ├── references/       # Extra docs, templates (optional)
│   ├── templates/        # File templates (optional)
│   └── scripts/         # Helper scripts (optional)

Command Create a New Skill

Create the skill directory and the SKILL.md file:

# 1. Create the skill directory
mkdir -p ~/.hermes/skills/my-custom-skill

# 2. Create the SKILL.md
touch ~/.hermes/skills/my-custom-skill/SKILL.md

# 3. Open and edit it
nano ~/.hermes/skills/my-custom-skill/SKILL.md

SKILL.md Format What Goes Inside

Every SKILL.md has two parts: frontmatter (metadata) and the body (instructions). Here's the template:

---
name: my-custom-skill
description: One-line description of what this skill does
trigger: When the user asks about [topic] or wants to [action]
category: productivity  # or: marketing, research, devops, etc.
---

# My Custom Skill

Describe the skill here. What does it do? When should it be used?

## Steps

1. [First step]
2. [Second step]
3. [Third step]

## Examples

Example 1:
User: "Can you [do the thing]?"
Agent: [How the agent responds]

Example 2:
User: "[Follow-up question]"
Agent: [Response]

## Pitfalls

- [Common mistake to avoid]
- [Another gotcha]

Command List All Available Skills

See every skill Hermes has access to:

ls ~/.hermes/skills/

# Or from inside Hermes CLI, type:
/skills

Tip What Makes a Great Skill

• Trigger conditions — When should this skill activate? Be specific.
• Step-by-step steps — Numbered steps the agent can follow exactly.
• Real examples — Show the skill in action with actual prompts and responses.
• Pitfalls — Tell the agent what to avoid, not just what to do.
• Verification — How does the agent know it succeeded? Include a check step.

Commands Identity & Persona Management

# See your current SOUL.md
cat ~/.hermes/SOUL.md

# Edit your SOUL.md
nano ~/.hermes/SOUL.md

# Switch to a different persona
cp ~/.hermes/personas/marketing-agent.md ~/.hermes/SOUL.md

# Create a new persona file from scratch
nano ~/.hermes/personas/my-new-agent.md

# See all your persona files
ls ~/.hermes/personas/

# Restore a backup
cp ~/.hermes/personas/current-SOUL.md.bak ~/.hermes/SOUL.md

Commands Skills Management

# List all skills
ls ~/.hermes/skills/

# Create a new skill
mkdir -p ~/.hermes/skills/my-skill
touch ~/.hermes/skills/my-skill/SKILL.md

# Delete a skill
rm -r ~/.hermes/skills/unwanted-skill

# View a skill's contents
cat ~/.hermes/skills/my-skill/SKILL.md

# Copy a skill to modify it
cp -r ~/.hermes/skills/code-review ~/.hermes/skills/my-code-review

Commands Hermes Desktop & Agent Control

# Start Hermes Desktop (if installed as AppImage)
~/Applications/hermes-desktop.AppImage

# Or if you installed it system-wide:
hermes-desktop

# Check if Hermes CLI is running
which hermes

# Check Hermes version
hermes --version

# Restart Hermes (kill then start)
pkill -f hermes-desktop
~/Applications/hermes-desktop.AppImage &

Commands Config & Diagnostics

# View your Hermes config
cat ~/.hermes/config.yaml

# View your API keys (never share this file)
cat ~/.hermes/.env

# Check Hermes logs
tail -n 50 ~/.hermes/logs/agent.log

# See errors from the last session
tail -n 30 ~/.hermes/logs/errors.log

# Find your Hermes home directory
echo $HERMES_HOME   # Usually ~/.hermes

Commands Quick Identity Swap Script

Save this as a shell script to instantly switch personas:

# Save as ~/switch-agent.sh and chmod +x ~/switch-agent.sh
#!/bin/bash
PERSONA=$1
if [ -z "$PERSONA" ]; then
  echo "Usage: ./switch-agent.sh [persona-name]"
  echo "Available personas:"
  ls ~/.hermes/personas/
  exit 1
fi
cp ~/.hermes/SOUL.md ~/.hermes/personas/current-SOUL.md.bak
cp ~/.hermes/personas/${PERSONA}.md ~/.hermes/SOUL.md
echo "Switched to $PERSONA. Restart Hermes to apply."

Usage: ./switch-agent.sh marketing-agent