hermes-fleet-starter

Personal-AI starter kit — declarative fleet management for Hermes Agent, preconfigured for a single user running on a Hostinger VPS.

This is a template repo. Click "Use this template" on GitHub to create your own copy, then follow the 4-step playbook below (or SETUP.md for the long form).

Quick start: 4 steps to a live agent

1. Provision a Hostinger VPS using the Hermes Agent Docker Compose Catalog template. Not a bare Ubuntu/Debian VPS — the entire pattern in this starter is built on top of Hostinger's bundled ghcr.io/hostinger/hvps-hermes-agent:latest image. (~$5/mo plan is sufficient.)
2. Use this template — click "Use this template" on this repo's GitHub page, name your repo, make it private, and clone it locally.
3. Open Claude Code in the clone and say "bootstrap my Hermes agent". Claude auto-discovers the skill at .claude/skills/hermes-fleet-setup/SKILL.md and walks you through SSH verification, a SOUL.md interview to define your agent's identity, persona rendering, lib/apply.sh, and OAuth login.
4. Wire up Telegram — create a bot with @BotFather, paste the token into your agent's web TUI via hermes auth add telegram. DM your bot.

You're live. To evolve from here — add specialists, change tone, upgrade Hermes — keep talking to Claude in the same repo; the skill stays applicable for the entire lifecycle.

If you'd rather drive each step manually, SETUP.md has the same flow with explicit commands and no Claude required.

What you get out of the box

• A lib/apply.sh reconciler that brings a Hermes agent up from zero on a fresh VPS in one command.
• A lib/doctor.sh health check that reports container, gateway, Hermes version, OAuth, and Telegram status.
• A lib/oauth_login.sh helper that drives loopback-OAuth flows (xAI SuperGrok, etc.) through an SSH tunnel for you.
• A lib/new_agent.sh scaffolder for adding more agents later.
• A lib/side_load.sh that pins your Hermes version to a specific upstream commit instead of waiting for the Hostinger image to ship features.
• Persona templates for an "Orchestrator + specialists" agent design (a Chief-of-Staff coordinator that delegates to focused subagent personas like general and xresearch).
• Documented procedures in docs/ for upgrading Hermes, switching personas, rotating credentials, and decommissioning agents.

What's NOT here (and why)

• No agent state (MEMORY.md, auth.json, kanban DB, sessions). Those live on your VPS and never enter the repo.
• No secrets. Admin credentials and bot tokens are passed via env vars at apply time.
• No personal content from previous setups. The persona files are templates with placeholders — your Claude Code (or you) fills them in during setup.

What the bootstrap skill does inside a session

When you do step 3 of the quick start — "open Claude Code and say 'bootstrap my Hermes agent'" — here's what's happening under the hood. Claude reads .claude/skills/hermes-fleet-setup/SKILL.md and:

1. Verifies SSH access to your Hostinger VPS and adds it to inventory.yaml.
2. Conducts a SOUL.md interview: ~15 questions about your name, the agent's name and role, values, philosophies, proactivity, tone, decision-making, privacy, scope, external systems (Obsidian/Notion/etc.), output preferences, and which specialists you want.
3. Renders the persona templates in templates/persona/ against your answers and commits them to agents/<your-agent>/.
4. Runs lib/apply.sh (provisioning the container, side-loading Hermes at the pinned SHA, applying config), lib/oauth_login.sh (model-provider login through an SSH tunnel), and points you at @BotFather for Telegram.
5. Stays applicable across future sessions — "add a code specialist", "upgrade Hermes", "decommission this agent" all keep using the same skill.

The skill defers to docs/RUNBOOK.md for procedures and docs/CUSTOMIZATION.md for the interview questions, so you can read either of those directly if you'd rather not interact through Claude.

Quick reference (after setup)

Task	Command
Bring an agent to its declared state	lib/apply.sh <agent>
Provision a new agent	lib/new_agent.sh <name>
Side-load Hermes at the pinned SHA	lib/side_load.sh <agent>
OAuth login for a provider on an agent	lib/oauth_login.sh <agent> <provider>
Health-check all agents	lib/doctor.sh
Bump Hermes version	edit pinned-versions.yaml → lib/apply.sh <agent>
Roll back Hermes	revert the commit, lib/apply.sh <agent>

Layout

agents/                  Per-agent declarative state (one dir per agent; empty until setup)
templates/               Files copied verbatim into a new agent
templates/persona/       Persona templates with {{placeholders}} the skill fills in
lib/                     Reconcilers and helper scripts
docs/                    ARCHITECTURE, ONBOARDING, RUNBOOK, CUSTOMIZATION, ROADMAP
.claude/skills/          Claude Code skills (auto-discovered when Claude is in this repo)
inventory.yaml           Hosts and agents → which host runs which agent
pinned-versions.yaml     Hermes git SHA + Python extras list
SETUP.md                 4-step playbook for first-time setup

See also

• SETUP.md — first-time setup, 4 steps from forking to live agent
• docs/ARCHITECTURE.md — how the side-load works and why
• docs/ONBOARDING.md — provisioning a per-agent (after the host is set up)
• docs/CUSTOMIZATION.md — SOUL.md interview reference + persona-template field guide
• docs/RUNBOOK.md — operational procedures (upgrade, rollback, troubleshoot)
• docs/ROADMAP.md — planned next steps and deferred work

Provenance

This repo was extracted from a working hermes-fleet deployment, sanitized for downstream forks. Personal content, agent state, and host-specific identifiers were stripped. Bug reports for the templates and lib scripts welcome at the upstream repo.