H+G

Hermes Agent + Grok CLI

Replicable Beginner Setup Guide

This is a self-hosted, beginner-friendly tutorial for setting up a governed Hermes Agent (thin orchestrator) + Grok Build CLI (sovereign brain) system on your own machine.

The steps are written generically so any reader can follow them. Replace example paths with your own (e.g. your home directory, your chosen workspace folder). The live version of this page is served from an example production deployment of this exact pattern.

Hermes Profile

orchestrator (example)

Thin meta-orchestrator layer

Standard: ~/.hermes/profiles/orchestrator

Grok Brain

~/.grok (example version)

Permanent, sovereign, native TUI first

Usually ~/.grok/bin/grok

Primary Workspace

your-grokswarm-workspace

Constitutional governance + your projects

This Guide

Self-served example

Adapt the deployment to your web server

How Hermes + Grok Work Together

Hermes (orchestrator profile — thin meta-layer)
├── Messaging gateway (Telegram, Discord, etc.) + home channel
├── Kanban board (decompose → route → track → human gates)
├── Cron jobs (recurring autonomous work)
├── Skills library (installable procedures & workflows)
└── Launch patterns → governed native Grok sessions
↓
Grok Build CLI (sovereign brain at ~/.grok)
├── Rule Zero (mandatory first SWARM PLAN)
├── 6 Personas + native subagents / worktrees / Plan Mode
└── Full execution inside your chosen workspace directory

Cross-project coordination: Your long-running projects live in or alongside the workspace.

Hermes is deliberately thin. It decides what and when. All real intelligence, personas, subagents, and deep work stay inside the sovereign Grok installation. "Native Grok Build TUI features first" is a core principle.

Prerequisites

• A supported OS (Windows, macOS, or Linux). This guide includes Windows-specific notes because many readers use it.
• Git Bash / terminal with bash (recommended on Windows) or your preferred shell.
• Administrator / sudo rights where needed for global installs or services.
• Internet access for downloads and authentication.
• Python 3.11+ (commonly required by Hermes).
• An account on a supported messaging platform if you want the gateway (Telegram is popular for always-on access).

Windows users: Many commands mangle backslashes. Prefer forward slashes (C:/...) in paths inside config files and use cmd.exe wrappers for certain native tools.

Step 1: Install the Grok Build CLI (The Permanent Sovereign Brain)

The Grok Build CLI is your permanent sovereign brain. It is installed separately from Hermes and is never replaced by it.

Obtain the binary: Place the Grok Build CLI so that the grok command works. Typical location: ~/.grok/bin/grok.
Verify:
```
grok --version
```
First-time authentication: Run grok. It will start an OAuth flow. Complete it in your browser. This authentication is independent of Hermes.
Important files you will see under ~/.grok:
- bin/grok
- AGENTS.md — enforces native TUI features first
- personas/ — the 6 personas as first-class definitions
- config.toml, auth files, logs, skills, sessions

Create a workspace directory (see next step). Many setups keep constitutional files (AGENTS.md / CONSTITUTION.md) inside the workspace so they are loaded when you set --cwd to it.

Step 2: Install Hermes Agent (The Thin Orchestrator)

Hermes acts as the persistent outer conductor (gateway, Kanban, cron, skills). Run it as a named profile (the "orchestrator" profile is a common pattern for a thin meta-layer).

Open a bash-capable terminal (Git Bash on Windows is common).

Install via the official script:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Run the setup wizard:
```
hermes setup
```
Create a dedicated profile (recommended for separation):
```
hermes profile create orchestrator
```
Switch to it:
```
hermes profile use orchestrator
```
Standard Hermes paths (adapt to your home):
- ~/.hermes/profiles/orchestrator/ — your config, skills, state, runtime info
- ~/.hermes/config.yaml and ~/.hermes/.env
- ~/.hermes/state.db — sessions + Kanban

Windows YAML note: Use single quotes or forward slashes for any paths containing backslashes inside double-quoted strings in config.yaml. Bad escapes cause the entire profile to fall back to defaults.

Step 3: Create Your Workspace Directory

Create a dedicated folder for governed work. This is where you will run Grok sessions with constitutional rules.

Example commands:

# Linux / macOS
mkdir -p ~/grok-swarm-workspace
cd ~/grok-swarm-workspace

# Windows (Git Bash or PowerShell)
mkdir -p C:/Projects/MyGrokSwarm
cd C:/Projects/MyGrokSwarm

Inside this folder you should place (or generate) AGENTS.md and CONSTITUTION.md files that define Rule Zero and the 6 personas (see the sections below for the exact content used in production setups).

When launching Grok for work in this workspace, always use --cwd "/path/to/your-grok-swarm-workspace" so the constitutional files are respected.

Step 4: Key Paths You Will Use

Grok CLI

~/.grok — main installation (bin/grok, personas/, config, auth)
~/.grok/bin/grok — the executable

Hermes

~/.hermes/profiles/<your-profile>/
~/.hermes/profiles/orchestrator/runtime-info/ — fast self-introspection (read these files instead of running slow CLI commands)
~/.hermes/state.db — Kanban + sessions (direct sqlite access is useful on some platforms)

Your Workspace

~/grok-swarm-workspace (or equivalent) — AGENTS.md, CONSTITUTION.md, kanban prompts, artifacts, your projects

Example Projects

Place your long-running work in or next to the workspace (research repos, engines, etc.). The orchestrator coordinates across them without replacing Grok's native capabilities.

Step 5: Rule Zero — Mandatory on Every Significant Task

This text (or a close equivalent) belongs in your workspace CONSTITUTION.md and must be respected on every significant task:

## Rule Zero — Mandatory Plan Entry Point

On **every** new significant task, the very first output produced by the swarm **must** be a clear, structured **SWARM PLAN** that:

1. Explicitly names the task.
2. Assigns specific responsibilities to one or more of the six canonical personas:
- Swarm Orchestrator
- Architect
- Technologist
- Creative Director
- Growth Operator
- Research Sage
3. States the rationale for the assignment.

No tool calls, no code generation, no parallel sub-agents, and no use of `execute-plan`, `implement`, `best-of-n`, or any other skill may occur until this plan has been presented and **explicitly approved** by the user.

Hermes launch helpers always inject this reminder when starting a session inside your workspace. The orchestrator itself can emit a compliant SWARM PLAN as a safe fallback.

Step 6: The 6 Canonical Personas

Persona	Primary Focus	Typical Use
swarm-orchestrator	Coordination, decomposition, synthesis, workflow	End-to-end ownership & delegation
architect	Strategy, risk, compliance, long-term vision, ADRs	Trade-off analysis & risk mgmt (often with plan mode)
technologist	Implementation, systems, DevOps, security, scale	Production-grade code & infra
creative-director	Content, design, branding, visuals, storytelling	High-impact narrative & assets
growth-operator	Marketing, psychology, virality, GTM, metrics	Audience & business acceleration
research-sage	Deep research, synthesis, fact-checking, intel	Evidence chains & truth-seeking (prefer explore type)

In native Grok sessions these are invoked via the task tool (with persona="...") or as dedicated agent types. Always start complex work by ensuring the full set of personas is represented in the SWARM PLAN.

Step 7: Kanban Orchestration & Governed Launches

Kanban for Multi-Agent Coordination

Use Hermes Kanban (via the orchestrator profile or dedicated workers) for decomposition, assignment, visibility, and human review gates. On platforms where the Hermes CLI is slow, direct database access to state.db is a reliable pattern.

Typical Governed Launch (adapt the path)

grok -p "Your goal here.

Remember Rule Zero from CONSTITUTION.md: produce a clear structured SWARM PLAN first naming the task and assigning the 6 personas. Wait for explicit approval before any tool use.

Operate inside /path/to/your-grokswarm-workspace under full constitutional governance." \
  --cwd "/path/to/your-grokswarm-workspace" \
  --max-turns 25 \
  --no-memory \
  --output-format plain \
  --no-alt-screen

Always set the correct --cwd to your workspace. Prefer --prompt-file for long constitutional reminders. Use --permission-mode plan for high-stakes architectural work.

Step 8: Messaging Gateway & Persistent Operation

Configure with hermes gateway setup and choose your platform(s).
Set a home channel for default delivery.
Install as a background service where possible: hermes gateway install then start/stop commands.
Cron jobs and Kanban keep long-running autonomous work alive.

Hermes supports many platforms (Telegram, Discord, Slack, etc.). The same agent instance can be reached from multiple channels with full tool access.

Core Capabilities of This Pattern

Orchestration & Persistence

• Launch and supervise native Grok sessions with full 6-persona + Rule Zero governance
• Kanban-based task decomposition, routing, visibility, and review gates
• Scheduled cron jobs for recurring autonomous work
• Long-running campaigns that survive restarts
• Skills that accumulate reusable procedures over time

Governance & Quality

• Strict adherence to native Grok Build TUI features first
• Institutional memory and a growing library of skills
• Thin-supervisor pattern (visibility without duplicating native capabilities)
• Cross-project coordination while keeping the sovereign brain in control
• Token-conscious, incremental, auditable workflows

Hermes never overrides the permanent Grok brain at ~/.grok. It provides the outer layer for strategy, persistence, scheduling, and human coordination while Grok performs the actual deep work using its native tools, personas, and Plan → Diff → Approval workflow.

Verification Steps

grok --version — confirm your Grok Build CLI is working.
cat ~/.hermes/profiles/orchestrator/runtime-info/profile (or equivalent) — should show your chosen profile name.
Navigate to your workspace and confirm it contains AGENTS.md / CONSTITUTION.md (or the Rule Zero text).

Run a safe constitutional test launch (replace the path):

grok -p "Output the exact text of Rule Zero from CONSTITUTION.md and the current SWARM PLAN template from AGENTS.md. Do not create any plan or do any work." --cwd "/path/to/your-grokswarm-workspace" --max-turns 5 --no-memory --output-format plain

If you deployed this guide as a webpage, verify it serves with a Host header test.
Check that your Kanban board is visible (via Hermes dashboard or direct DB query) and that new cards can be created.

This is a generic, replicable guide. Adapt the paths, workspace name, and deployment method to your environment.
The live page you are reading is an example deployment of the pattern described here.
Governance content (Rule Zero, personas) is drawn from production constitutional documents and is intended to be universal.
Updated for generic use • Self-served