hubzoid 1.0.1

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 helps builders turn a useful personal agent into something their team can use. A Hub holds instructions, knowledge, skills, tools, and agent definitions in a versionable folder. Workflows, team chat, and supported assistants reuse the relevant parts under the hub's access rules.

Start on your laptop. Add the context and capabilities your team needs. Bring the hub to a shared deployment when you are ready to manage accounts, permissions, and ongoing operation.

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.

Your context is worth keeping

The terminology, the decisions, the way your team checks a report—this is the context that makes an agent useful. Keep it alongside reusable skills and tools in a Hub instead of copying it into every prompt or rebuilding it for each chat surface. Update the source files as the team learns, review them in Git, and reuse the relevant parts wherever the work happens.

Business data can stay in its source systems. Connect it through Python tools or MCP, and grant the capabilities each person needs. Shared context does not mean shared credentials or unrestricted access.

One hub, three ways to work

These experiences share a foundation. Conversation history, workflow state, and permissions remain distinct. Each integration has its own setup and supported capabilities.

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 work your team already does

A useful Hub begins with a specific job. These are examples you can build with hub knowledge, tools and workflows; connecting your real systems is part of setup.

For example, a purchasing Hub can define what counts as an overdue order once. A workflow produces the daily report; a teammate asks which suppliers need attention; a personal assistant uses the authorized reporting tools while drafting a follow-up. Each experience uses the same maintained definition, with access checked for the caller.

From your laptop to your team

• Keep context in files. Review changes in Git and maintain the knowledge the agent relies on.
• Connect existing systems. Use MCP connectors, user-owned connections, or Python tools. Keep credentials separate from agent-readable material.
• Grant capabilities deliberately. The Admin Console manages agent entry and restricted tools. Enforcement happens outside the model, with recorded allow and deny decisions.
• Inspect what ran. View usage, workflow results, steps, people, and activity. Estimated model cost is guidance; your provider's bill is authoritative.
• Choose a runtime. Hubzoid supports OpenAI Agents, Claude Agent and local Codex backends. Provider and channel capabilities vary; use the provider guide for the supported paths.
• Operate one or several hubs. Run one hub or use hubzoid gateway for a shared chat app and deployment. Back up before upgrades and verify access with ordinary user accounts.

Open WebUI supplies chat and account authentication. Hubzoid's Admin Console supplies access management and execution inspection at /portal/. Administrators see an Admin Console link above their profile in the chat sidebar (an icon when collapsed). There is one account system. With public sign-up closed by default, an administrator uses Add user in the Admin Console, from an agent's Access page or from People, to create a login account and give it access in one step; an existing user's access is changed with Edit access. Nothing is sent: the administrator shares the sign-in details. With Google sign-in and OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true configured, Google sign-in only creates an account with no password to share.

The dashboard brings agent cards together with messages, users, token usage, workflow runs and approximate cost. Open an agent to manage access, inspect its runs and schedules, or review activity. Restricted capabilities remain enforced by Hubzoid before the tool runs, rather than by an instruction asking the model to behave.

Try a worked example

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

# Workflow example with bundled metrics
hubzoid init watchtower --template watchtower

The template catalog also has examples for briefings, accounts, supplier checks, inventory, Q&A, and operations. Examples use sample data and placeholder integrations where stated. Inspect their README before connecting real systems or enabling schedules.

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. See the contributor guide.

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.