ScarabHive

ScarabHive

The right model for every agent, as much structure as each task needs -- and a live view of what every agent really does.

ScarabHive is a flexible, powerful, self-hosted framework for LLM agents, built entirely on plugins. You define an agent in YAML -- its model, its prompt, the few tools it may use -- and run it in the browser, from the command line or as a model behind an OpenAI-compatible API. Not a library to build an app on: the whole runtime ships -- agent loop, sessions, tools, a web UI and the API -- so agents are configured, not coded.

Built on current technology throughout: the providers' newest APIs and features -- OpenAI's Responses and Realtime APIs, extended and adaptive thinking, prompt-cache breakpoints, batch APIs -- and the open standards around agents: MCP (stdio and streamable HTTP), the Agent Skills format and OpenTelemetry's GenAI conventions.

Quick start · Why ScarabHive · Plugins · Web UI, CLI and API · Documentation · Discussions

Highlights

• A model per agent -- fallback chains, a stronger model for hard tasks, any provider, local models, batch APIs, Claude Code as a tool.
• From one agent to fixed workflows -- one agent with skills, an agent with specialised sub-agents, or a state machine.
• Lean on tokens -- cache-friendly requests, a context that stays small, fewer turns per task.
• Live observability -- every step, every tool call, the raw requests, the cost of every call.
• Plugins all the way down -- about 75 ship with it; tools, panels and hooks of your own are a small folder each.
• Every agent is a model -- behind an OpenAI-compatible API, next to a web UI and a CLI.

Quick start

You need Python 3.11 or newer (3.12 recommended), git, about 2 GB of disk and an LLM provider. For the simplest start, take an OpenRouter API key: as shipped, every agent that is switched on runs on OpenRouter. To use OpenAI, Anthropic, Google Gemini, DeepSeek or a local Ollama instead, point the profiles in config/llm.yaml and config/llm_openrouter.yaml at their models (how).

git clone https://github.com/eehrich/ScarabHive.git ScarabHive
cd ScarabHive
./install.sh                                            # Linux, macOS, Git Bash
powershell -ExecutionPolicy Bypass -File install.ps1    # Windows PowerShell

The script installs everything into .venv, creates a signing key for this installation, asks for a password for the admin account (Enter generates one) and opens http://127.0.0.1:8000. Log in as admin, open the Setup panel and enter your key. Docker, a manual installation and troubleshooting: INSTALLATION.md.

Your first agent is one YAML file, config/agents/summarizer.yaml:

plugins:
  servers:
    summarizer:
      type: basic_agent
      enabled: true
      metadata: {visibility: both}
      agent_config:
        llm_profile: [turbo, normal]     # a cheap, fast model first, then a fallback
        system_prompt: "Summarise what you are given in five bullet points."
        tools:
          allowed: ["web_scraper/*"]     # the only tools it may call

source .venv/bin/activate          # Linux, macOS; Git Bash: .venv/Scripts/activate; PowerShell: .venv\Scripts\Activate.ps1
agent-cli run --agent summarizer "Summarise https://example.com"

After a restart of the server, the same agent is in the web UI and is the model summarizer behind the OpenAI-compatible API. More: config-based agents.

See it in action

▶ Watch the ScarabHive playlist on YouTube.

Who it is for

• Developers who build on agents: plugins in plain Python, scripted runs, agents called as models from their own code, and a coding agent that works in their repositories.
• Teams that bring agents into their company's workflows (more).
• Content creators who build multi-step workflows -- research, images, audio, video -- from agents and tools, with little or no code.

Why ScarabHive

The right model for every agent

• One model per job. Every agent names its own LLM profile: a cheap, fast model for summaries and lookups, a strong one for code or judgement. Sub-agents and plugins (a summariser, for example) name their own. A profile is a fallback chain: when a model fails or is rate-limited, the next one takes over.
• A stronger model when the task gets hard. An agent can carry a second, stronger chain. A caller asks for it when it hands over a hard task. With auto_escalate_on_stuck switched on, the run also switches up by itself when it gets stuck -- caught in a tool-call loop, or failing tool after tool -- for a few steps within a call budget, then drops back to the normal model (LLM profiles).
• Any provider, local models included. OpenAI (Chat Completions and Responses), Anthropic, Google Gemini, OpenRouter, DeepSeek, Ollama, and any OpenAI-compatible server such as vLLM or llama.cpp. Batch APIs for Gemini, OpenAI and Anthropic, picked like any other model (batch).
• Your Claude Code subscription as a tool (experimental). An agent can hand a coding task to Claude Code, which runs on your Claude Code login instead of an API key, in an isolated copy of the repository; its changes come back for you to review (coding_cli).

As much freedom as the task needs

Pick the structure that fits, from loose to fixed:

1. One agent that does it all, with skills (packaged instructions it loads when needed) and OKF knowledge bundles (Markdown files linked into a graph, which it reads and keeps up to date).
2. One agent with specialised sub-agents, each with its own model and only the tools its job needs. The coding agent that ships works this way: an explorer and a reviewer that can only read, a test runner, and the coder that writes. Sub-agents run in parallel or in the background and wake their caller when done (sub-agents).
3. A fixed workflow as a state machine (young: 0.1). Agents, tools and Python functions are the steps; branches, parallel steps and a person's approval are part of the graph. Runs are journaled and resume after a crash, and a graph editor with breakpoints and watchpoints debugs them (stategraph). A machine can itself be offered as an agent.

Built to spend less

• Optimised for the prompt cache. Each request extends the previous one; nothing that changes from call to call sits at the front, and tests guard it. Cache breakpoints and cache keys are set where a provider needs them.
• A context that stays lean. For agents that switch on the context engineer (the shipped multi-turn agents do), large tool results move out of the context and stay readable on demand, and long conversations are compacted. Old messages are summarised by a cheap model.
• Fewer turns and fewer tokens. A script can chain several dependent tool calls in one model turn; predictable opening tool calls can run before the first LLM call; rarely used tools reach the model as a name and one line until it asks for them (deferred tools).
• Runs that stop wasting. Tool-call loops and reasoning loops are detected and stopped, and a message you send while an agent works reaches it at its next step.

See what the model really does

• While it runs: every LLM step with its thinking, every tool call with its result, and every sub-agent, live in the chat; a map of all sub-agents of a session and what each one is doing.
• Down to the wire: the raw requests and responses each model got and gave, in the Message Debugger.
• What it cost: tokens, cache hits and cost of every call, per session, agent and model.
• A second opinion, for agents that switch it on: a watchdog in which a cheap model judges every few steps whether a run is still making progress. Traces can go to OpenTelemetry once you enable that plugin.

Built on plugins

Everything is a plugin -- tools, hooks around the model call, panels in the UI, agents with their prompts and skills, slash commands, even the LLM providers. About 75 ship with it.

• An agent gets only the tools it needs. Its allowlist starts empty; patterns allow and deny tools per plugin instance, and rarely used ones can be deferred. An agent can also be put in ask mode, where a person approves each tool call before it runs. Fewer tools mean a smaller attack surface and fewer tokens on every call.
• Built for debugging. The Message Debugger, the cost panel, a log viewer, the state-machine debugger, agent-cli hooks inspect, and a Help panel with a manual for every plugin -- for those that give the model tools, exactly what the model sees of them.
• Your own plugin is a small folder. Three files for a tool, a panel built on the shipped UI kit, hooks before and after every LLM call. Skills that know how plugins and panels are built ship with the repository, for Claude Code and for ScarabHive's own coding agent (plugin-authoring, panel-authoring); validators check the result.

A tool, beside a short plugin.toml that names the plugin:

# src/plugins/greeter/schema.yaml -- what the model sees
tools:
  - type: function
    function:
      name: "{{ name }}_hello"
      description: Greet a person by name.
      parameters:
        type: object
        properties:
          who: {type: string}
        required: [who]

# src/plugins/greeter/plugin.py -- one method per tool
from typing import Any

from agent_system.tools.schema_based import SchemaBasedToolServer


class GreeterServer(SchemaBasedToolServer):
    async def hello(self, params: dict[str, Any]) -> dict[str, Any]:
        return {"status": "success", "greeting": f"Hello, {params.get('who')}!"}


PLUGIN_FACTORY = GreeterServer

Switch it on in config/plugins.yaml and give an agent +greeter/* in its tool list. The whole walk-through, plugin.toml included: docs/plugin_authoring.md; hooks: docs/plugin_hooks.md; a working example plugin.

Web UI, CLI and API

• Web UI: a streaming chat with sessions per user, and panels you dock as tabs or open as windows -- agents, sub-agents, state machines, costs, raw requests, logs, setup and more.
• CLI: agent-cli chat and agent-cli run work without a server and share the sessions with the web UI; agent-run for scripted runs (CLI reference).
• API: every agent is a model behind an OpenAI-compatible endpoint (/chat/completions and /responses, text in and out), next to the REST and streaming API the web UI uses (openai_api).

In a company

• Users and roles: admin, user and guest, logins by password or API key, and rules per role for which routes and panels each one may open.
• Agents with limits: each agent can be restricted to a minimum role, starts without tools until its allowlist names some, and can ask a person before a tool runs.
• Integration: agents as models for your own code and tools; n8n workflows built as drafts and tested with every outbound call mocked; external MCP servers as tools.
• Deployment: install scripts, or Docker Compose with the port on loopback only (INSTALLATION.md); report vulnerabilities privately (SECURITY.md).

What ships with it

• Files and shell: file operations confined to configured folders; a terminal (unrestricted by default -- a command whitelist, or write confinement on Linux and macOS, narrows it); file checkpoints with undo, SSH to remote machines, SQLite queries.
• Web: search (Tavily, DuckDuckGo), page scraping, a research agent that answers with sources.
• Knowledge: memory, a todo list, lessons an agent learns from its runs, skills, OKF bundles.
• Development: the coding agent with its sub-agents, Claude Code as a delegate, Godot and Blender agents.
• Media: images, audio and video into and out of the context, image composition, ComfyUI.

A look inside

Cost, tokens and cache use of every call	The sub-agents of a session as a map
Agents edited in a form, their YAML and comments kept	Setup: what the installation still lacks

Documentation

• INSTALLATION.md — from a checkout to the first login
• docs/configuration.md — models, plugins, agents, authentication
• The Help panel in the UI — the manual for the framework and each plugin (docs/guides/, src/plugins/<name>/<name>.guide)
• docs/plugin_authoring.md and docs/plugin_hooks.md — writing your own plugins
• docs/ — architecture and design notes

Questions and contributing

Questions, ideas and what you built with it: GitHub Discussions. Bugs: issues. Contributions: see CONTRIBUTING.md.

Status

[!WARNING] ScarabHive is beta software. It is under heavy development and may contain serious bugs, including ones that lose data, run up LLM costs or weaken security. Behaviour, configuration and APIs can change without notice. Do not expose it to the internet or to people you do not trust. Keep backups of everything under data/, and watch your providers' spending limits. Report security issues privately, as described in SECURITY.md.

License

Apache License 2.0, see LICENSE.

Author

Enrico Ehrich