hubzoid 0.9.6

Internal AI agents that work for your team.
_{The open-source framework for enterprise internal agents: self-hosted, defined in markdown, run inside your own perimeter.}

One folder becomes a production agent

An internal agent does the work your team does by hand, on the systems your company already runs: the morning briefing, the supplier bill check, the stock drift scan, a plain answer in Slack to "what did we bill last month".

Hubzoid turns a folder of markdown into that agent, complete and deployable. 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 an audit log for restricted tools.

Deploy the same agent to the web, Slack, WhatsApp, Telegram, generic webhooks, and MCP clients. Connect it to the systems your company 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.

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? Add a key and model to my-hub/.env first -- see Providers.

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

Internal agents, not customer-facing bots

Hubzoid builds internal agents: the ones your own team uses for its own work in operations, finance, leadership reporting, IT-ops, and knowledge. The agent's user is your team, never your customers. Internal work has provable ROI, and a wrong answer reaches your own team, not a customer.

Templates

templates/ holds six complete hubs for common internal roles. Each one runs as-is on sample data, with clearly marked placeholder tools in tools_local/ where a real system (ledger, ERP, alerting) is wired in later.

Copy one and run it:

cp -r templates/morning-briefing my-hub
hubzoid run my-hub

See templates/README.md for who on the team uses each one, which surfaces to turn on, and where the real systems plug in.

What you get

Security and control

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: allow and deny decisions on restricted tools are appended to an audit log with the user, surface, tool, result, and reason. Read it with hubzoid audit.
• 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 collector or Langfuse.

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 below, 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.

Surfaces

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

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

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. More surfaces are on the roadmap.

Tools and connectors

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 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.
5. Shared browser (HUBZOID_BROWSER=true) gives every agent the full Playwright toolset backed by one shared, resource-limited browser — so N agents don't mean N browsers. One flag; MCP wiring is automatic.

See MCP connectors, MCP server mode, and shared browser.

Automation

Put a markdown task in schedule/ and the hub becomes an unattended agent. A task runs on a five-field cron or fires from an incoming webhook, using the same persona, skills, knowledge, tools, and model as chat inside a bounded run with timeouts, persistent progress, and path-scoped writes. Each run produces a live JSONL log and can commit or push only declared paths. See scheduled tasks.

Gateway

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 surface, and consistent branding. Each hub keeps its own instructions, tools, knowledge, schedules, and model. See production deployment.

Evals and observability

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 to Langfuse or through your existing OTel collector. See evals and observability.

Editing your hub

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

1. Pick your model. .env selects the model. See Providers.
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).
• Memory backends for cross-session recall.
• Sandboxed eval (record/replay tool mocking) and multi-turn cases.
• Sandboxed code execution (Python in a container) and browser automation.
• Pluggable agent runtimes beyond the two shipped SDKs, and chat frontends beyond Open WebUI.

Need it built for your company?

Hubzoid is MIT-licensed and complete; run it yourself. If you would rather have your internal agents built, deployed, and handed over at a fixed price, that is what hubzoid.com does. Start with an agent map.

Contributing

See CONTRIBUTING.md. Issues and PRs welcome.

License

MIT -- all of it, including access controls, gateways, scheduling, evals, and integrations. No enterprise edition, no license key, no feature gates. Use it, modify it, self-host it, and ship it in production. See LICENSING.md.