sharbelxyzandClaude Opus 4.8
2cfa033ed9
- Committed SVG hero (Calm Luxury: near-black ground, blue accent, Postgres-bus architecture motif) rendered inline on GitHub - Shields badges for the stack - Native [!IMPORTANT] callout at the top so a Hermes handed only the repo URL knows to clone, read ONBOARDING.md, and guide the install - "Two ways to install" section (agent-driven vs by hand) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
249 lines
9.9 KiB
Markdown
249 lines
9.9 KiB
Markdown
<div align="center">
|
|
|
|
<img src="./public/hermy-hq-banner.svg" alt="Hermy HQ — mission control for your self-hosted Hermes agent" width="100%" />
|
|
|
|
<p><strong>Your own mission control for a self-hosted AI agent.</strong></p>
|
|
|
|
<p>
|
|
<img src="https://img.shields.io/badge/Next.js-16-0A0B0D?style=for-the-badge&logo=nextdotjs&logoColor=white" alt="Next.js 16" />
|
|
<img src="https://img.shields.io/badge/React-19-141821?style=for-the-badge&logo=react&logoColor=6EA8FE" alt="React 19" />
|
|
<img src="https://img.shields.io/badge/Prisma-Postgres-141821?style=for-the-badge&logo=prisma&logoColor=white" alt="Prisma + Postgres" />
|
|
<img src="https://img.shields.io/badge/Tailwind-v4-141821?style=for-the-badge&logo=tailwindcss&logoColor=6EA8FE" alt="Tailwind v4" />
|
|
<img src="https://img.shields.io/badge/pairs%20with-Hermes-6EA8FE?style=for-the-badge" alt="Pairs with Hermes" />
|
|
</p>
|
|
|
|
</div>
|
|
|
|
Hermy HQ is a self-hostable dashboard template that pairs with your own local
|
|
[Hermes agent](https://github.com/NousResearch/hermes-agent). The website is your
|
|
cockpit: dispatch work, review the agent's plans, approve anything with side effects,
|
|
browse its memory, and watch it run, all from one place. Your Hermes stays on your
|
|
own machine; the website and the agent talk to each other through a shared Postgres
|
|
database acting as a message bus.
|
|
|
|
It is a **template and starting point**, not a hosted product. You bring your own
|
|
database, your own Hermes, and your own API keys. Everything is configured through
|
|
environment variables.
|
|
|
|
---
|
|
|
|
> [!IMPORTANT]
|
|
> **🤖 If you are an AI agent reading this repository**
|
|
>
|
|
> The person who gave you this link wants you to **install Hermy HQ for them**. Do this:
|
|
>
|
|
> 1. **Clone** this repository to the machine you operate on.
|
|
> 2. **Open [`ONBOARDING.md`](./ONBOARDING.md)**, a complete step-by-step installer written for you.
|
|
> 3. **Follow it in order**, guiding your human through each step: prerequisites, `.env`, database, local run, Vercel deploy, and the bridge.
|
|
> 4. **Pause to ask them for every real secret** (API keys, database URL, OAuth credentials). **Never invent or guess credentials**, and keep every side-effecting action approval-gated.
|
|
>
|
|
> `ONBOARDING.md` is the full guided install. Start there.
|
|
|
|
---
|
|
|
|
## 🚀 Two ways to install
|
|
|
|
- **🤖 Let your agent do it (easiest).** Send this repo to your Hermes and paste the contents of [`ONBOARDING.md`](./ONBOARDING.md). It onboards you step by step, pausing for each secret.
|
|
- **🔧 By hand.** Follow the [Quick start](#quick-start) below.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
**Cockpit**
|
|
- Dashboard home with an at-a-glance view of the agent, tasks, and the day
|
|
- ⌘K command palette to jump anywhere or fire an action
|
|
- Chief-of-Staff daily brief, generated on a schedule
|
|
|
|
**Hermes control hub** (`/hermes`)
|
|
- Dispatch one-shot prompts or kanban tasks to the agent
|
|
- Approval inbox — side-effecting requests wait here for your explicit go-ahead
|
|
- Live activity feed and run history
|
|
- Cron list and health mirrored from the agent
|
|
|
|
**Memory**
|
|
- Memory Wiki — browse and edit the agent's memory (facts, notes, links) as a wiki
|
|
|
|
**Work & content**
|
|
- Tasks and Ideas boards
|
|
- Content OS — an X / Twitter content pipeline (drafts, scoring, scheduling)
|
|
- Longform + YouTube script studios
|
|
- Client Pulse — a client-health tracking board (bring your own data ingestion)
|
|
- Agents roster, Garden, and Watchlist Radar
|
|
|
|
> Some features need your own API keys (YouTube, X/Twitter, OpenAI, etc.). They are
|
|
> all optional and configured via env — the core dashboard runs without them.
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
The deployed website never talks to your agent directly. Both sides read and write
|
|
the **same Postgres database**, which acts as a message bus. A small **bridge**
|
|
process runs on the machine where Hermes lives.
|
|
|
|
```
|
|
┌───────────────────────┐ ┌────────────────────────┐
|
|
│ Hermy HQ (website) │ │ Your machine / server │
|
|
│ Next.js on Vercel │ │ │
|
|
│ │ │ ┌───────────────┐ │
|
|
│ • dispatch requests │ │ │ hermes-bridge │ │
|
|
│ • approval inbox │ │ │ (bridge.mjs) │ │
|
|
│ • activity / runs │ │ └──────┬────────┘ │
|
|
│ • memory wiki │ │ │ hermes CLI │
|
|
└──────────┬────────────┘ │ ┌──────▼────────┐ │
|
|
│ │ │ Hermes │ │
|
|
│ │ │ agent │ │
|
|
│ │ └───────────────┘ │
|
|
│ └───────────┬────────────┘
|
|
│ │
|
|
▼ ▼
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ Postgres (message bus) │
|
|
│ AgentRequest · AgentEvent · HermesTask · HermesMemory │
|
|
│ DataStore · Brief · … │
|
|
└────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
- **Website → agent:** the site inserts an `AgentRequest`. Safe requests are
|
|
`queued`; anything side-effecting is `awaiting_approval` until you approve it in
|
|
the inbox.
|
|
- **Bridge → agent:** the bridge polls Postgres, runs `queued`/`approved` requests
|
|
via the `hermes` CLI, and writes results back. It never runs `awaiting_approval`.
|
|
- **Agent → website:** the bridge mirrors the kanban board (`HermesTask`), cron +
|
|
health (`DataStore`), memory (`HermesMemory`), and activity (`AgentEvent`) back
|
|
into Postgres, where the website reads them.
|
|
|
|
Nothing on your machine is exposed to the internet — the bridge only needs outbound
|
|
access to Postgres and your local `hermes` CLI. See
|
|
[`hermes-bridge/README.md`](./hermes-bridge/README.md) for details.
|
|
|
|
---
|
|
|
|
## Tech stack
|
|
|
|
- **Framework:** Next.js 16 (App Router) + React 19
|
|
- **Styling:** Tailwind CSS v4
|
|
- **Data:** Prisma ORM + PostgreSQL
|
|
- **Auth:** NextAuth with Google login (email allowlist)
|
|
- **Charts / DnD:** Recharts, react-dnd
|
|
- **Deploy:** Vercel (website) + launchd/systemd (bridge)
|
|
- **Agent:** [Hermes](https://github.com/NousResearch/hermes-agent) `hermes` CLI
|
|
|
|
---
|
|
|
|
## Quick start
|
|
|
|
### Prerequisites
|
|
|
|
- **Node.js 20+** (22 recommended) and **git**
|
|
- A **PostgreSQL** database URL — e.g. [Neon](https://neon.tech),
|
|
[Prisma Postgres](https://www.prisma.io/postgres), [Supabase](https://supabase.com),
|
|
or Vercel Postgres
|
|
- A **Hermes agent** installed on a machine you control (the `hermes` CLI on PATH)
|
|
- **Google OAuth** credentials (Client ID + Secret) for login
|
|
- A **Vercel** account (or any Node host) for deploying the website
|
|
|
|
### 1. Clone and install
|
|
|
|
```sh
|
|
git clone <your-fork-url> hermy-hq
|
|
cd hermy-hq
|
|
npm install
|
|
```
|
|
|
|
### 2. Configure environment
|
|
|
|
```sh
|
|
cp .env.example .env
|
|
```
|
|
|
|
Open `.env` and fill in at least the **required core** vars: `DATABASE_URL`,
|
|
`POSTGRES_URL`, `NEXTAUTH_URL`, `NEXTAUTH_SECRET`, `GOOGLE_CLIENT_ID`,
|
|
`GOOGLE_CLIENT_SECRET`, `ALLOWED_EMAILS`, and `NEXT_PUBLIC_OWNER_NAME`.
|
|
Every variable is documented inline in [`.env.example`](./.env.example).
|
|
|
|
Generate a secret with:
|
|
|
|
```sh
|
|
openssl rand -base64 32
|
|
```
|
|
|
|
### 3. Create the database tables
|
|
|
|
```sh
|
|
npx prisma db push
|
|
```
|
|
|
|
### 4. Run locally
|
|
|
|
```sh
|
|
npm run dev
|
|
```
|
|
|
|
Open <http://localhost:3000> and sign in with a Google account whose email is in
|
|
`ALLOWED_EMAILS`.
|
|
|
|
### 5. Deploy to Vercel
|
|
|
|
```sh
|
|
npm i -g vercel # if you don't have it
|
|
vercel # link + deploy a preview
|
|
vercel --prod # production
|
|
```
|
|
|
|
Then:
|
|
|
|
1. Add **every** env var from your `.env` in **Project → Settings → Environment
|
|
Variables**.
|
|
2. Set `NEXTAUTH_URL` and `NEXT_PUBLIC_BASE_URL` to your production URL.
|
|
3. In the Google Cloud console, add the authorized redirect URI
|
|
`https://<your-domain>/api/auth/callback/google`.
|
|
|
|
### 6. Connect your Hermes (the bridge)
|
|
|
|
On the machine where Hermes lives, set up the bridge so the bus connects:
|
|
|
|
```sh
|
|
cd hermes-bridge
|
|
npm install
|
|
DATABASE_URL='postgres://…same as the website…' HERMES_BOARD=default node bridge.mjs
|
|
```
|
|
|
|
You should see `hermes-bridge up …` and a **"Bridge connected"** event appear in the
|
|
website's activity feed. To keep it running, install it via launchd (macOS) or
|
|
systemd (Linux) — full instructions in
|
|
[`hermes-bridge/README.md`](./hermes-bridge/README.md).
|
|
|
|
---
|
|
|
|
## Project layout
|
|
|
|
```
|
|
src/ Next.js App Router (dashboard, /hermes, memory-wiki, content-os, …)
|
|
prisma/ schema.prisma (message-bus + feature models)
|
|
hermes-bridge/ the bridge that runs on your machine next to Hermes
|
|
.env.example every env var, documented
|
|
ONBOARDING.md copy-paste prompt to have your Hermes install this for you
|
|
```
|
|
|
|
---
|
|
|
|
## Safety
|
|
|
|
Hermy HQ is designed so the agent can act, but not surprise you:
|
|
|
|
- Requests that have side effects are marked `sideEffecting` and land in the
|
|
**Approval Inbox** as `awaiting_approval`. The bridge will not run them until you
|
|
approve.
|
|
- The bridge lives on your machine and only reaches out to Postgres and the local
|
|
`hermes` CLI — nothing inbound.
|
|
- Login is Google OAuth gated to the emails in `ALLOWED_EMAILS`.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Provided as a template for you to fork, self-host, and adapt. Add the license of
|
|
your choice before publishing your own instance.
|