Self-Hosted AI Agent Server

One brain.
Many heads.
Infinite reach.

Install Linux. Install HydraHive. Done.
Manage your entire AI agent swarm from a single web console — no Docker, no cloud dependency.

Quick Start How it works →
HydraHive — The self-hosted agent swarm platform.
No cloud. No lock-in. Full control.

Everything you need. Nothing you don't.

Built for real infrastructure. No Docker networking nightmares.

🧠

Boss + Worker Swarms

One Boss-Agent per project coordinates a pool of specialists in parallel. Results aggregated, streamed token-by-token to the user.

🔌

One-Command Install

One bash command. GPU auto-detected. Matrix, nginx, TLS, systemd — all configured. Web console ready in minutes.

💬

Matrix Communication

Agents are real Matrix bots. Use Element to supervise any conversation live. Built-in watchdog restarts crashed bots automatically.

🤖

Multi-LLM per Agent

Each agent runs its own model. Ollama locally, Claude Max (OAuth), OpenAI — mixed per task. Configurable temperature and token limits.

📚

QMD Skills

Give agents extra knowledge via Markdown files with YAML frontmatter. Scope: always or keyword-triggered on-demand. Hot-reload, no restart.

📁

Project Isolation

Each project gets a Linux user, isolated filesystem, Samba share, and Matrix room. Agents can only access their own project directory.

🧑‍💻

Personal Agent

Every user gets a private agent (personal_<username>) with its own chat, skills, memory and workstation access — completely independent of projects.

🧠

Memory System

Agents store knowledge in Markdown files, auto-injected into every session. Combine with QMD semantic search to save tokens on large memory sets.

💻

WKS Access

Personal agents SSH into your workstation — run commands, read and write files. WKS Ollama models appear automatically in the model dropdown.

🔧

Git Integration

Agents commit, push, and create pull requests on Gitea. Full git workflow from chat — no terminal needed.

🔌

MCP Servers

Connect external tool servers via streamableHttp (Model Context Protocol). Ships with QMD — semantic memory search built in.

🔗

Webhook System

Trigger agents from external systems — Git pushes, CI pipelines, monitoring alerts. HMAC-signed outgoing webhooks included.

🛡️

Security & Audit

JWT auth, login rate-limiting, atomic config writes, three-layer tool permission model. Full audit log of all user actions.

🖥️

Full Web Console

Manage agents, projects, users, skills, webhooks, MCP servers and LLM config — all without SSH. One-click system update included.

🔄

Heartbeat Monitoring

Schedule recurring tasks for any agent — system checks, log scans, API pings. Non-trivial findings automatically escalated to another agent via AgentLink.

💾

Backup & Restore

One-click full-system backup from the web console. Agents, projects, config and skills — all in one archive. Restore to any point with a single upload.

🕸️

AgentLink Hub

Built-in agent coordination bus. Agents hand off tasks, share context and escalate findings across projects — or across machines in a multi-node setup.

How it works

A message travels through 10 layers in under a second.

👤 Web Chat
→
⚡ FastAPI Core
→
📡 Matrix Room
→
🧠 Boss Agent
→
🐍 Worker Swarm
→
✅ SSE Stream

The user sees a clean streaming chat. The agents do the rest — with full Matrix audit trail.

Architecture

Clean separation of concerns. Every layer replaceable.

┌─────────────────────────────────────────┐
│ CLIENT React Console · Element · REST API │
├─────────────────────────────────────────┤
│ GATEWAY nginx HTTPS · JWT Auth · Rate Limit │
├─────────────────────────────────────────┤
│ CORE FastAPI · Orchestrator · Audit Log │
├─────────────────────────────────────────┤
│ COMM BUS conduwuit Matrix · Agent Bots │
├─────────────────────────────────────────┤
│ LLM ADAPTER Ollama · Claude OAuth · OpenAI │
└─────────────────────────────────────────┘

Stack

Boring technology. Battle-tested components.

Core
Python 3.12 + FastAPI litellm · matrix-nio · anthropic SDK
Console
React 18 + TypeScript Vite · Tailwind CSS · shadcn/ui
Matrix
conduwuit (Rust) Single binary · RocksDB · no Postgres
LLM
Ollama + Cloud APIs llama3 · Claude · OpenAI · mixed per agent
Infrastructure
Bash + systemd No Docker · idempotent installer
Platform
Ubuntu 22/24 LTS Proxmox VM · PCIe GPU passthrough

Deployment Profiles

Start small. Scale to full GPU when ready.

🔵 Lite

Cloud APIs · No GPU required
  • Any VM or VPS
  • Claude Max OAuth + OpenAI
  • Full web console
  • Matrix communication
  • All project features
  • HTTPS out of the box

🟣 Full

Local LLMs · GPU Passthrough
  • PCIe GPU passthrough (e.g. GTX 1080)
  • Ollama — llama3.1:8b default
  • No API costs for local tasks
  • Hybrid: local + cloud per agent
  • Auto-detected at install time
  • Reference: GTX 1080 Ti, 11GB VRAM

Agent System

From the handbook — how agents, skills and projects work together.

Agent Types

🎯 Boss
Receives user messages, coordinates worker agents, streams results back
🔬 Specialist
Domain expert delegated tasks from Boss — tax, legal, code, etc.
⚡ Worker
Short-lived task agent, spawned on-demand, discarded after completion

QMD Skills

---
skill: Tax Law Basics
scope: on-demand
triggers: [tax, vat, income]
priority: 10
---
## Knowledge content here...

Hot-reload. No restart needed. Injected into system prompt on keyword match.

Available Tools

file_read — read project files
file_write — write project files
web_search — search the web
http_request — call external APIs
dispatch_task — delegate to workers (boss only)
spawn_agent — create short-lived agent

Data Flow A → Z

From the technical docs — what happens when a message is sent.

1
Browser — POST /projects/{id}/message/stream → nginx (TLS termination) → FastAPI
2
Auth — JWT validated, project loaded, asyncio.Queue selected
3
Matrix — Message enqueued → Boss-Agent's Matrix room → matrix-nio client
4
Skills — Skill files scanned, always-loaded + keyword-matched injected into system prompt
5
LLM — litellm routes to configured provider (Ollama / Claude / OpenAI), streaming enabled
6
Tools — Tool calls intercepted, executed via registry, results returned to LLM (multi-turn)
7
Workers — dispatch_task → parallel worker calls → aggregated results back to Boss
8
Response — Final answer posted to Matrix room, stored in session history
9
SSE — Core dequeues tokens → data: {"text":"..."} → Browser renders Markdown
✓
Done — data: {"done":true} → stream closed → Audit Log written

Quick Start

Three commands. One browser tab. Running.

$ git clone https://github.com/HydraHive/hydrahive.git
$ cd hydrahive
$ sudo bash installer/install.sh
 
# → open https://<your-ip> → Setup Wizard → done

Documentation

Everything you need to install, use, and extend HydraHive.

📖

Handbook

Installation, setup wizard, agents, projects, chat, LLM config, troubleshooting
⚙️

Technical Docs

Architecture, module overview, data flow A–Z, error handling, known limitations
🔌

API Reference

All REST endpoints with request/response examples — agents, projects, webhooks, audit
🛠️

Developer Guide

Write tools, skills, endpoints, Console pages — extend HydraHive with new features
Production ready — actively developed
Core complete · Console complete · Docs complete · API not yet stable