Hermes-first Agent Runtime Manager

Local web console for operating multiple Hermes-first AI agent profiles on Windows, macOS, and Linux.

Agent Runtime Manager discovers Hermes profiles, creates new runnable profiles, edits profile files safely, manages channel credentials, controls native or Docker runtime processes, tracks logs/events, and creates portable profile backups. It is designed for local-first multi-agent operations where each profile can have its own prompt, memory, skills, .env, runtime state, and LLM engine link.

Keywords

Hermes AI, AI agent runtime manager, local AI agents, multi-agent operations, Docker Hermes profiles, LM Studio, OpenAI-compatible LLM, Codex login, FastAPI, React, Windows macOS Linux.

Features

• Discover existing Hermes native profiles and Hermes Docker container profiles.
• Create new Hermes profiles with profile-specific SOUL.md, config.yaml, .env, memory, sessions, and skills directories.
• Rename profile display names and actual Hermes profile folder names.
• Start, stop, and restart managed profiles with per-agent runtime locks.
• Prevent unsafe duplicate messaging-token usage across concurrently running gateways.
• Edit prompt, config, env, memory, skills, and text assets with conflict detection and automatic backups.
• Configure Telegram, Discord, email, Slack, and custom webhook gateway environment values.
• Register OpenAI-compatible local LLM engines, LM Studio endpoints, and Codex-login engines.
• Run environment diagnostics for OS, Python, Docker CLI/daemon, Hermes executable/home/profile paths, Codex auth, and LLM endpoints.
• Inspect cron jobs, Docker mounts, logs, events, runtime metadata, and profile backup capsules.
• Build source-only archives that exclude secrets, databases, virtual environments, node modules, build output, local logs, and backups.

Repository Hygiene

This repository intentionally does not include machine-local runtime state.

Excluded by .gitignore:

• data/, SQLite databases, logs, backups, and generated source archives
• backend/.venv/, pytest cache, Python bytecode, and coverage output
• frontend/node_modules/, frontend/dist/, Vite cache, and TypeScript build info
• .env, auth.json, token-like files, and local credential material
• legacy source dumps and editor/OS noise

Fresh clones create their own local data/app.sqlite, frontend build output, virtual environments, and runtime settings.

Local Profile Boundary

Installing, cloning, pulling, starting, or rescanning this app must not reset or seed Hermes profile files. The app treats the machine's installed Hermes profiles as external local state and discovers them from the configured Hermes home, default profiles path, custom search paths, and Docker containers.

Read-only discovery may update the manager's local SQLite metadata, such as profile paths, display names for discovered profiles, and runtime status. It must not write to existing profile files like SOUL.md, config.yaml, .env, memories, sessions, or skills. Profile files are written only after explicit user actions such as creating a profile, editing a file, copying a skill, changing a linked LLM engine, starting runtime features that intentionally write manager request artifacts, or restoring a backup.

License

MIT License. See LICENSE.

Requirements

• Python 3.12 or newer
• Node.js 20 or newer
• Docker Desktop on Windows/macOS, or Docker Engine on Linux
• PowerShell on Windows, zsh/bash on macOS, or bash on Linux

The backend serves frontend/dist when it exists, then falls back to frontend/static. The launcher scripts build the React frontend automatically when frontend/dist is missing.

Quick Start

Clone the repository:

git clone https://github.com/miter37/agent-runtime-manager.git
cd agent-runtime-manager

Install backend dependencies:

cd backend
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
cd ..

Run the app:

./scripts/start-agent-runtime-manager.sh

The script prints the backend/UI URL, usually http://127.0.0.1:8765.

Windows Quick Start

git clone https://github.com/miter37/agent-runtime-manager.git
cd agent-runtime-manager
cd backend
python -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"
cd ..
.\scripts\start-agent-runtime-manager.ps1

Or double-click/run the batch launcher:

Start-Agent-Runtime-Manager.bat

macOS And Linux Notes

Use the bash launcher:

./scripts/start-agent-runtime-manager.sh

Or run the root launcher:

./Start-Agent-Runtime-Manager.sh

On Linux, make sure the current user can access Docker, or Docker diagnostics and Docker profile control will report permission or daemon errors.

Frontend Development

Use Vite when editing frontend/src:

cd frontend
npm install
npm run dev -- --host 127.0.0.1 --port 5173

Keep the backend running on the URL printed by the launcher. If the launcher selected a port other than 8765, point Vite at it:

VITE_BACKEND_URL=http://127.0.0.1:8766 npm run dev -- --host 127.0.0.1 --port 5173

Windows PowerShell equivalent:

$env:VITE_BACKEND_URL = "http://127.0.0.1:8766"
npm run dev -- --host 127.0.0.1 --port 5173

Build the production frontend:

cd frontend
npm install
npm run build

Environment Diagnostics

Open Settings after the backend starts. The diagnostics panel reports:

• current OS and Python executable
• Docker CLI and Docker daemon availability
• Hermes executable detection
• Hermes home and profile path existence
• Codex auth file detection
• OpenAI-compatible endpoint health checks

Defaults

• Backend binds to 127.0.0.1.
• SQLite database is created locally at data/app.sqlite.
• Default Hermes home is ~/.hermes.
• Default profiles path is ~/.hermes/profiles.
• A default local LLM engine is seeded if no LLM engines exist:
  • http://127.0.0.1:1234/v1
  • local-model

Safety Model

• Discovered profiles are not controlled until explicitly registered.
• New profiles get their own profile-specific .env.
• Existing profiles that fall back to shared Hermes home .env are flagged in the UI.
• File saves create timestamped backups before writes.
• File writes use mtime/hash conflict detection.
• Secrets are masked by default in UI payloads.
• Runtime operations are guarded by per-agent locks and logged as events.
• Profile rename is blocked while the profile is running.
• Default Hermes profile rename is blocked.

Validation

Run backend tests:

backend/.venv/bin/python -m pytest backend/tests

Run frontend type-check/build:

cd frontend
npm run build

The source archive workflow is also tested by extracting the archive into a temporary directory and verifying backend tests plus frontend npm ci && npm run build.

Source Archive

Create a source-only transfer package without local data, virtual environments, node modules, build output, SQLite files, backups, or auth/token files.

Windows:

.\scripts\create-source-archive.ps1

macOS/Linux:

./scripts/create-source-archive.sh

The scripts write an archive and a manifest under dist/.

Architecture

• Backend: FastAPI, SQLite, local services for discovery, runtime control, file sync, backups, Docker interaction, LLM engine status, and diagnostics.
• Frontend: React, Vite, TypeScript, TanStack Query, and local static serving through the FastAPI backend.
• Runtime support: native Hermes profile folders and Hermes profiles inside Docker containers.

Status

The project is actively evolving toward stronger Windows/macOS/Linux parity, richer cron management, more explicit multi-agent queue visibility, and eventual desktop packaging.