---
title: Introduction
description: Install Hubzoid, create a shared Hub, connect supported chat and MCP clients, restrict tools in code, deploy it and operate it with your team.
canonical_url: https://hubzoid.com/docs
last_updated: 2026-09-27
---

# 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.

The [architecture](https://hubzoid.com/docs/concepts/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](https://hubzoid.com/docs/getting-started/installation): Install Hubzoid with pip or Docker and check it with the doctor command.
- [2. Quickstart](https://hubzoid.com/docs/getting-started/quickstart): Create a Hub, pick a model and have your first conversation.
- [3. Start from a template](https://hubzoid.com/docs/getting-started/templates): 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](https://hubzoid.com/docs/guides/markdown-tasks) |
| Run exact steps in code and call the agent for judgment | [Code workflows](https://hubzoid.com/docs/guides/code-workflows) |
| Let the agent read a system my team uses | [Tools and connectors](https://hubzoid.com/docs/guides/tools-and-connectors) |
| Let only some people use a sensitive tool | [Restrict a tool](https://hubzoid.com/docs/guides/restrict-tools) |
| Use the Hub from Claude Code, Codex or Hermes | [Connect an assistant](https://hubzoid.com/docs/guides/connect-an-assistant) |
| Share an agent I already built on my laptop | [Bring an existing agent](https://hubzoid.com/docs/guides/existing-agents) |
| Add the agent to Slack, WhatsApp or Telegram | [Slack](https://hubzoid.com/docs/chat/slack), [WhatsApp and Telegram](https://hubzoid.com/docs/chat/whatsapp-and-telegram) |
| Check the agent keeps doing its job | [Evals](https://hubzoid.com/docs/guides/evals) |
| Run it on a server for my team | [Single server](https://hubzoid.com/docs/deploy/single-server) |

## Browse the docs

- [Getting started](https://hubzoid.com/docs/getting-started/installation): Install Hubzoid, create a Hub and have your first conversation.
- [Concepts](https://hubzoid.com/docs/concepts/architecture): How the Hub, agents, models, memory and workflows fit together.
- [Guides](https://hubzoid.com/docs/guides/design-an-agent): Step-by-step tasks for building, automating and sharing an agent.
- [Chat surfaces](https://hubzoid.com/docs/chat/web-chat): Web chat, Slack, WhatsApp, Telegram and the OpenAI-compatible API.
- [Console](https://hubzoid.com/docs/console/overview): Grant access, follow runs and review activity across agents.
- [Deploy and operate](https://hubzoid.com/docs/deploy/topologies): Run one Hub or many on a server or in Docker, then keep them healthy.
- [Reference](https://hubzoid.com/docs/reference/cli): 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](https://hubzoid.com/docs/getting-started/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](https://hubzoid.com/docs/chat/web-chat) and [Slack](https://hubzoid.com/docs/chat/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](https://hubzoid.com/docs/concepts/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](https://hubzoid.com/docs/guides/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](https://hubzoid.com/docs/concepts/memory-and-history) and [identity and access](https://hubzoid.com/docs/concepts/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](https://hubzoid.com/docs/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](https://hubzoid.com/docs/concepts/agents-and-models#runtimes). The [architecture](https://hubzoid.com/docs/concepts/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.

```text
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/.
```