hubzoid 0.9.3

Your AI agents. Every channel. Every tool. Under your control.
_{The open-source platform for governed, production AI agents. Self-hosted, defined in markdown, and MIT licensed—all of it.}

One folder becomes a production agent

Hubzoid turns a folder of markdown into a complete, deployable AI agent. Define its instructions, sub-agents, skills, knowledge, tools, access rules, schedules, and evals alongside each other. Hubzoid supplies the runtime, streaming API, chat UI, channel adapters, identity, authorization, automation, and audit trail.

Deploy the same agent to the web, Slack, WhatsApp, Telegram, generic webhooks, and MCP clients. Connect it to the systems your organization already uses. Run one hub for one team, or put many role-specific hubs behind one shared login and centrally managed front door.

The hub stays portable. Run it with the OpenAI Agents SDK or the Claude Agent SDK, and choose models from OpenAI, Anthropic, Azure OpenAI, OpenRouter, or local Claude through your existing CLI subscription.

The complete agent platform, without the platform lock-in

Enterprise control. Open-source freedom.

Hubzoid is designed to run inside your perimeter and use the identity systems you already trust.

• Authentication: email and password, Google, Microsoft, GitHub, generic OIDC, or LDAP through Open WebUI.
• Agent visibility: gateway groups control which teams can discover and use each hub.
• Tool authorization: sensitive tools live in restricted/; matching groups grant access. Unknown identities and unverified surfaces fail closed.
• Credential isolation: secrets for restricted tools cannot be read through the agent's file tools. Supported MCP services can use a different encrypted OAuth token for every user.
• Auditability: every restricted-tool decision records the user, surface, tool, result, and reason.
• Deployment choice: run on a Linux host, in Docker, or under ECS, Kubernetes, and other orchestrators. Keep telemetry local or send standard OpenTelemetry traces to your existing collector or Langfuse.

There is no proprietary control plane and no commercial code hidden elsewhere. Deploy Hubzoid yourself, modify it, and redistribute it without changing platforms or asking for permission.

Quickstart

Three commands if the claude CLI is installed and logged in.

pip install hubzoid
hubzoid init my-hub                    # minimal runnable hub + agents-repo wrapper
hubzoid run my-hub

Open http://localhost:3080. You get a generic assistant with one example of every Hubzoid surface (one skill, one knowledge file, one sub-agent, one custom tool) so the folder layout is obvious. Edit my-hub/AGENTS.md to make it yours.

Using OpenAI, Anthropic, Azure OpenAI, or OpenRouter instead? Add the provider key and model to my-hub/.env before running the hub.

Want the guided tour instead? hubzoid init my-hub --template demo gives a Hubzoid Guide agent that explains the framework as you chat.

One agent, every surface

Same agent, same skills, same knowledge, same .env. Pick the surfaces you want.

More surfaces are on the roadmap.

hubzoid run my-hub --slack --whatsapp --telegram   # any combination, one process

Slack uses Socket Mode, so it needs no public endpoint. WhatsApp and Telegram use verified inbound webhooks and a per-hub identity/access.csv roster that maps each sender to an email and groups. Unknown senders are rejected before an LLM or tool runs. Conversation memory, per-sender identity, access gating, attachments, and channel-native response updates are built in.

Connect the tools your organization already runs

Hubzoid does not make you rebuild integrations inside a proprietary platform. Use the lightest standard that fits:

1. Shared MCP connectors give a hub centrally configured tools and data.
2. Per-user MCP connections let each person connect supported services with OAuth in Open WebUI; Hubzoid executes with that person's encrypted token.
3. Hub-local Python tools wrap an internal API or workflow with a normal typed function.
4. The MCP server exposes the hub's governed tools and knowledge to other AI clients under the caller's identity and group permissions.

Connectors behave the same under both supported agent runtimes. MCP servers are read-only by default, and HTTP access can be limited with an allowlist. See MCP connectors and MCP server mode.

Automate work, not just conversations

Put a markdown task in schedule/ and the hub becomes an unattended agent. A task can run on a five-field cron or fire from an incoming webhook. It uses the same persona, skills, knowledge, tools, and model as chat, inside a bounded run harness with timeouts, persistent progress, and path-scoped writes.

Every run produces a live JSONL log. Tasks can safely update selected hub files, commit only declared paths, and optionally push the result so CI and review workflows continue normally. Scheduled evals use the same scheduler to catch model or data drift. See scheduled tasks and evals.

Operate every hub from one front door

hubzoid gateway places multiple independent hubs behind one shared Open WebUI. Users sign in once and see only the agents granted to their team. Operators get one user directory, one group-management surface, consistent organization-wide branding, and one place to register user-connected MCP services.

Each hub keeps its own instructions, tools, knowledge, schedules, model, and artifact space. Run everything on one host or split the bridges across your infrastructure. See production deployment.

Measure quality, usage, and cost

Behavioral evals live beside the agent in evals/*.md. Assert required answer content, required tool calls, forbidden tools, and model-judged criteria. Run the same suite during development, as a CI gate, or on a schedule.

Opt-in OpenTelemetry traces capture the interaction, model requests, tool calls, user identity, tokens, and cost. Send them directly to Langfuse or through your existing OTel collector; a shared backend can separate every hub and user without a Hubzoid-specific telemetry service. See observability.

A minimal AGENTS.md

---
name: code-reviewer
description: Reviews a code diff. Ranks the top three issues by severity.
model: openrouter/anthropic/claude-haiku-4.5
---

You review code. When the user pastes a diff or a file, identify the top
three issues ranked by severity: correctness first, then security, then
readability.

For each issue, cite the line number and explain the fix in one sentence.
Skip style nits unless the user asks for them. If the code looks clean,
say so in one line and stop.

That is the whole hub. One file. No sub-agents, no skills, no knowledge needed. Drop it in a folder, run hubzoid run ., and you have a code reviewer at http://localhost:3080 -- and, if you flip on the surfaces above, in Slack, WhatsApp, and Telegram too.

How it works

┌─────────────────────────────┐
│  Surfaces                   │  Web · Slack · WhatsApp · Telegram · MCP
└──────────────┬──────────────┘
               │ OpenAI-compatible HTTP
┌──────────────┴──────────────┐
│  FastAPI bridge             │  /v1/chat/completions  /v1/models
└──────────────┬──────────────┘
               │ in-process
┌──────────────┴──────────────┐
│  Agent runtime              │  OpenAI Agents SDK  |  Claude Agent SDK
└──────────────┬──────────────┘
               │ LiteLLM (or claude CLI subprocess)
┌──────────────┴──────────────┐
│  Your model                 │  OpenRouter · OpenAI · Anthropic · claude-local
└─────────────────────────────┘

One install command provides the UI, API bridge, both agent runtimes, model routing, channel adapters, scheduler, access layer, and built-in tools.

Editing your hub

Your hub is one folder. The pieces you can add:

1. Pick your model. Default .env uses MODEL=claude-local (no key needed if claude login is done). To switch to OpenRouter / OpenAI / Anthropic, uncomment a stanza in .env and paste a key.
2. Write the main agent. AGENTS.md body is the system prompt. Frontmatter sets name, description, optional model, and optional suggestions: (quick-start prompts shown as buttons on the empty chat screen).
3. Sub-agents. One folder per sub-agent under agents/, each with its own AGENTS.md. Frontmatter tools: [...] whitelists which tools it may call.
4. Skills. One folder per playbook under skills/, each a SKILL.md. Loaded on demand via load_skill(name).
5. Knowledge. One markdown file per topic under knowledge/, reached via read_knowledge(name).
6. Tools and connectors. Drop Python files with @function_tool in tools_local/. Edit connectors/.mcp.json to plug in MCP servers.
7. Unstructured data. Drop code repos or document dumps into raw_data/. The agent searches it with grep_data and reads files with read_file. No indexing step -- the folder ships with the hub.
8. Scheduled tasks. One markdown file per background job under schedule/. Frontmatter sets the cron cadence; the body is plain-English instructions the hub's own agent runs unattended while hubzoid run is up. See docs/schedule.md.
9. Evals. One markdown file per behavioural check under evals/ -- a prompt plus what the answer must do. Run by hand, from CI (exit code is the gate), or on a cron. See docs/evals.md.

Folder names are case- and plural-flexible (skills/, Skills/, skill/ all work). Changes are picked up on the next start.

mkdir my-agents && cd my-agents
hubzoid init devops-agent       # creates ./devops-agent + ./requirements.txt + ./.gitignore + ./README.md
hubzoid init support-agent      # creates ./support-agent only; parent files left alone
hubzoid init research-agent     # creates ./research-agent only

# OpenRouter (one key, many models)
OPENROUTER_API_KEY=sk-or-v1-...
MODEL=openrouter/anthropic/claude-haiku-4.5

# OR OpenAI
OPENAI_API_KEY=sk-...
MODEL=openai/gpt-4o-mini

# OR Anthropic
ANTHROPIC_API_KEY=sk-ant-...
MODEL=anthropic/claude-haiku-4-5

# OR Claude local (uses your installed `claude` CLI + Pro/Max subscription)
# Requires `claude login` first. No API key needed.
MODEL=claude-local              # defaults to Haiku 4.5 (~3x faster TTFT than Sonnet)
# MODEL=claude-local/sonnet     # opt in to Sonnet
# MODEL=claude-local/opus       # opt in to Opus

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "./workspace"]
    }
  }
}

# <hub>/.env
MCP_SERVER=true

hubzoid init [NAME]              Scaffold a new hub folder under the current directory.
  --template, -t NAME              "minimal" (default) or "demo" (guided tour).
hubzoid run [PATH]               Start the FastAPI bridge plus Open WebUI for a hub.
  --port INT                       Public Open WebUI port (default 3080).
  --bridge-port INT                FastAPI bridge port (default 8000, loopback).
  --no-ui                          Bridge only, no Open WebUI / edge.
  --slack, -s                      Also start the Slack adapter inline.
  --whatsapp / --telegram          Also start the inbound webhook surfaces inline.
hubzoid gateway [HUBS...]        One shared Open WebUI fronting many hub bridges.
hubzoid schedule list [PATH]     List the hub's scheduled tasks + next fire times.
hubzoid schedule run PATH TASK   Fire one task NOW, in-process.
hubzoid schedule status [PATH]   Show recorded fire history per task.
hubzoid eval run [PATH]          Run evals/*.md against the hub's agent (exit code = CI gate).
hubzoid eval list/status/explain Inspect and debug eval cases.
hubzoid doctor [PATH]            Validate hub config and report issues.
hubzoid audit [PATH]             Show the access log for restricted tools.
hubzoid test [PATH]              Send one prompt to the agent and print the response.
hubzoid slack run/manifest/systemd [PATH]     Run the hub as a Slack bot. See docs/slack.md.
hubzoid inbound run/systemd [PATH]            Serve the WhatsApp/Telegram webhook app.
hubzoid version
hubzoid --help

git clone https://github.com/hubzoid/hubzoid.git
cd hubzoid
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
hubzoid run demo-hub

Open standards

Hubs are portable across any tool that adopts these specs (Claude Code, Cursor, Codex, Copilot, Gemini CLI, VS Code).

Roadmap

• More chat surfaces (Gmail and others).
• Mem0 / Zep memory backends.

Contributing

See CONTRIBUTING.md. Issues and PRs welcome.

License

MIT -- all of it. Use it, modify it, self-host it, and ship it in production. See LICENSING.md.