hubzoid 1.0.2

One brain for your internal agents.

Provide context once. Reuse it across workflows, chat, and the AI tools your team already uses.

Documentation · Quickstart · Website · Contribute

Hubzoid is an open-source, self-hostable platform for internal AI agents. Keep your team's knowledge, instructions, skills, and tools in a versionable folder. Use that shared Hub through chat, repeatable workflows, or your own assistant through MCP.

Start with a useful agent on your laptop. Give it the context and capabilities it needs, then share it with your team using accounts and scoped permissions.

Start a hub

Use Python 3.11 or 3.12 in a virtual environment. Fresh interactive setup detects signed-in Claude or Codex CLIs and saves your choice. Without a selection, the default remains claude-local. Prefer an API provider? Configure a model and key in my-hub/.env before running. See providers.

python3.12 -m venv .venv
source .venv/bin/activate
pip install hubzoid
hubzoid init my-hub
hubzoid run my-hub

Workflows on Python 3.12: the workflow engine (DBOS, which runs markdown schedules and code workflows) needs SQLite 3.42 or newer, or PostgreSQL. Check with the same Python the hub uses: python -c "import sqlite3; print(sqlite3.sqlite_version)". hubzoid doctor reports it as deps.sqlite. Python 3.11 is not affected.

Open localhost:3080, select your agent, and try “Say hello using the hello skill.” The minimal template includes a skill, knowledge file, custom tool, and sub-agent you can inspect and change. Edit my-hub/AGENTS.md to make the hub yours.

The default is local single-user mode. For a shared deployment, enable authentication and configure the intended owner before exposing the public port. See administration. This branch's changes may be ahead of the package published on PyPI; source installation tests the checked-out revision.

One hub, three ways to work

Business data can stay in its source systems, connected through tools or MCP. Shared context does not mean shared credentials: conversation history, workflow state, and permissions remain distinct. Each integration has its own setup.

A hub is a folder

my-hub/
├── AGENTS.md        Main agent instructions
├── knowledge/       Reference material
├── skills/          Reusable instructions, loaded when needed
├── agents/          Specialist agent definitions
├── tools_local/     Python tool factories
├── restricted/      Tools that require explicit permissions
├── connectors/      External MCP connections
├── schedule/        Markdown tasks
├── workflows/       Python workflows and steps
└── evals/           Behavioural checks

Only AGENTS.md is required for the hub structure. Runtime credentials and configuration still need to be set. Start small and add files when they become useful. Author a hub →

Start with a useful job

Examples use sample data and placeholder integrations where stated. Read the example's instructions before connecting real systems or enabling schedules. Browse all templates →

Share it with your team

• Connect existing systems. Add Python tools and MCP connections. Keep credentials separate from agent-readable files.
• Control who can do what. Grant agent access and restricted capabilities in the Console. Hubzoid checks permissions before a restricted tool runs.
• See what happened. Inspect workflow runs, steps, usage, and activity. Model cost estimates are guidance; your provider's bill is authoritative.
• Choose your runtime. Use OpenAI Agents, Claude Agent SDK, or local Codex. Provider and channel capabilities vary. See providers.
• Run it yourself. Deploy one hub, or use hubzoid gateway to serve several hubs through a shared chat app. See deployment.

Open WebUI provides chat and account authentication. Hubzoid's Console at /portal/ manages access and shows execution details, using the same accounts. Administrators can open it from the Admin Console link in the chat sidebar. For adding teammates, Google sign-in, permissions, and shared deployment setup, see administration.

Try a worked example

# Guided chat tour
hubzoid init guided-hub --template demo

For a small Python workflow:

hubzoid new workflow first-check my-hub
hubzoid schedule run my-hub first_check

The scaffold runs on demand and needs no model or external service. Add a schedule only when you want unattended execution. The Console inspects runs; CLI commands operate them.

Documentation

The website documentation is the reading and discovery surface. The guides in this checkout describe this revision and remain available when working offline or reviewing a change.

Browse all guides →

Contribute

Read CONTRIBUTING.md and the product direction. Propose non-trivial changes as text in proposals/ before large implementations. Keep integration and maintenance costs low; preserve the hub-folder contract and runtime neutrality.

pip install -e '.[dev]'
pytest

Real-provider tests are separate and skip without credentials. Changes to the Console also require its build and browser checks. CI runs when a GitHub release is published, so run the relevant checks locally before pushing. See contributing and publishing a release.

License and help

Hubzoid product code, including team controls, is Apache-2.0 licensed. Dependencies, optional services, fonts, and brand assets retain their own terms. See LICENSE and LICENSING.md.

Need help building or operating your team's agent? Implementation assistance uses the same open-source product.