Introduction
Install Hubzoid, create a shared Hub, connect supported chat and MCP clients, restrict tools in code, deploy it and operate it with your team.
Hubzoid is an open-source platform for internal AI agents. You describe what an agent knows and can do in one folder, the Hub, and Hubzoid runs that same foundation wherever your team works: in a web chat, in Slack, WhatsApp and Telegram, on a schedule, in response to a webhook, and inside AI assistants people already use through the Model Context Protocol (MCP).
Provide context once. Reuse it across workflows, chat, and the AI tools your team already uses.
How it fits together
Hubzoid runs on your own machine or server. Chat, workflows and assistants connected over MCP all reach the same Hub through one bridge per Hub. The bridge checks who is asking, runs the agent or the workflow with the Hub's context and tools, and calls the model provider and systems you configure. Administrators add users, manage access and follow each agent's usage and runs in the Console.
Where your team works
Chat
Web chat, Slack, WhatsApp, Telegram and the OpenAI-compatible API.
Workflows
Markdown tasks and code workflows on a schedule, from a webhook or on demand.
Your assistant
Claude Code, Codex and other MCP clients, through
/mcp.
Hubzoid, on your machine or serverOne bridge per Hub
Identity and access
Checks who is asking before the agent or a restricted tool runs, and records each tool decision.
Agent runtime
Builds the agent from the Hub and runs it on the OpenAI Agents SDK, the Claude Agent SDK or local Codex.
Workflow engine
Runs scheduled, webhook and manual work durably, with a run history.
The Hub, your folder in Git
AGENTS.mdknowledge/skills/tools_local/restricted/workflows/
Instructions, knowledge, skills, tools and recurring work. Every service above reads the same files.
Console
/portal/Administrators add users, grant access per agent, follow usage and runs, and read the activity log.
Your data
Grants, runs, usage and web chat history, in SQLite by default or PostgreSQL.
What it calls
Your model provider
OpenAI, Anthropic, Azure OpenAI, OpenRouter, or
claude-localandcodex-localthrough a logged-in local CLI.Your systems
Only through the tools and MCP servers you add to the Hub.
The architecture page follows one request through every process and port.
Start here
New to Hubzoid? These three pages take you from nothing to a working agent on your laptop.
1. Install
Install Hubzoid with pip or Docker and check it with the doctor command.
2. Quickstart
Create a Hub, pick a model and have your first conversation.
3. Start from a template
Run a ready-made Hub on sample data, then adapt it to your work.
I want to
| Task | Read |
|---|---|
| Put a recurring task on a schedule | Markdown tasks |
| Run exact steps in code and call the agent for judgment | Code workflows |
| Let the agent read a system my team uses | Tools and connectors |
| Let only some people use a sensitive tool | Restrict a tool |
| Use the Hub from Claude Code, Codex or Hermes | Connect an assistant |
| Share an agent I already built on my laptop | Bring an existing agent |
| Add the agent to Slack, WhatsApp or Telegram | Slack, WhatsApp and Telegram |
| Check the agent keeps doing its job | Evals |
| Run it on a server for my team | Single server |
Browse the docs
Getting started
Install Hubzoid, create a Hub and have your first conversation.
Concepts
How the Hub, agents, models, memory and workflows fit together.
Guides
Step-by-step tasks for building, automating and sharing an agent.
Chat surfaces
Web chat, Slack, WhatsApp, Telegram and the OpenAI-compatible API.
Console
Grant access, follow runs and review activity across agents.
Deploy and operate
Run one Hub or many on a server or in Docker, then keep them healthy.
Reference
Every CLI command, configuration key, Hub file, built-in tool and endpoint.
What is in a Hub
A Hub is a folder of Markdown, YAML and small Python files that you keep in Git.
| Part | Where it lives | What it does |
|---|---|---|
| Instructions | AGENTS.md | The main agent's system prompt, name, description and model. |
| Knowledge | knowledge/*.md | Reference material the agent reads on demand with read_knowledge. |
| Skills | skills/*.md or skills/<name>/SKILL.md | Step-by-step playbooks loaded with load_skill. |
| Agent definitions | agents/*.md or agents/<name>/AGENTS.md | Sub-agents, loaded inline as skills or run on their own model as delegates. |
| Tools | tools_local/*.py, connectors/.mcp.json | Python functions and MCP servers the agent can call. |
| Authorized tools | restricted/*.py | Tools that run only for people granted the matching permission, including the account a workflow runs as. |
| Recurring work | schedule/*.md, workflows/<name>/*.py | Markdown tasks and Python code workflows on the durable workflow engine. |
The project structure page lists every file and folder Hubzoid reads.
Three ways to use the same Hub
- Chat. Teammates ask questions and request actions in the bundled web chat (Open WebUI), in Slack, WhatsApp and Telegram, or through an OpenAI-compatible API. See web chat and Slack.
- Workflows. Repeatable work runs on a cron schedule, on demand, or when a webhook arrives. Markdown tasks hand instructions to the Hub's own agent. Code workflows run exact Python steps and call the agent where judgment is needed. See workflows and schedules.
- Your assistant through MCP. With
MCP_SERVER=true, the Hub serves its tools and knowledge at/mcp, so Claude Code, Cursor and other MCP clients use the same context under each caller's own identity. See connect an assistant.
These experiences overlap. A scheduled task uses the same persona, skills, knowledge and tools as chat. Each surface keeps its own conversation history and its own access rules, described in memory and history and identity and access.
The Console at /portal/ is where administrators add users, grant each person access per agent, follow each agent's usage and runs, and read the activity log of access changes and tool decisions. See the Console overview.
Three agent runtimes are included. Any LiteLLM model id (OpenAI, Anthropic, Azure OpenAI, OpenRouter) runs on the OpenAI Agents SDK. MODEL=claude-local runs on the Claude Agent SDK through your installed claude CLI and its subscription. MODEL=codex-local runs on local Codex through your logged-in Codex CLI. See agents and models. The architecture page shows every process and port.
Who it is for
- Builders. People who understand a business process and already get useful results from AI. You write the Hub, test it on your laptop with
hubzoid run, and hand it to your team without rewriting it. - Teammates. People who use the result. They chat with the agent in the tools they already have and never need to know how it is built.
- Owners and administrators. People responsible for access, operation and cost. They sign in to the Console to add users, grant capabilities per agent, follow usage, runs and failures, and review who used which restricted tool.
Hubzoid is open source under the Apache 2.0 license, including access controls, the gateway, scheduling and evals. You run it on your own machine, a Linux server or in Docker.
For AI coding agents
If you build with Claude Code, Codex or another coding agent, paste this prompt into it from an empty project folder. Replace the text in angle brackets with the job you want the agent to do.
Set up a local Hubzoid Hub in this folder.
1. Create a Python 3.11 or 3.12 virtual environment and run: pip install hubzoid
2. Run: hubzoid init my-hub
This creates my-hub/ with AGENTS.md, a .env file and one example of each folder.
3. Pick the model in my-hub/.env.
If the `claude` CLI is installed and logged in, keep MODEL=claude-local.
If only Codex CLI 0.147.0 is installed with a file-backed login, set MODEL=codex-local.
Otherwise ask me which provider to use, then set MODEL and its key:
OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY,
or AZURE_API_KEY with AZURE_API_BASE.
4. Run: hubzoid doctor my-hub
Fix every check marked as failed before continuing.
5. Rewrite my-hub/AGENTS.md for this job: <describe the job in one paragraph>.
Put reference material in my-hub/knowledge/<topic>.md and procedures in
my-hub/skills/<name>/SKILL.md, each with name and description frontmatter.
6. Run: hubzoid test my-hub --prompt "What can you help me with?"
7. Start it with: hubzoid run my-hub
Then tell me to open http://localhost:3080
Keep secrets only in my-hub/.env. Do not commit .env, .hubzoid/ or .openwebui-data/.