Templates
The three templates bundled with the Hubzoid package and the six role-specific Hubs in the repository, what each contains, and how to start from one.
You can start a Hub from a blank folder, but a template shows the layout with working files. Hubzoid has two kinds:
- Bundled templates ship inside the Python package.
hubzoid initscaffolds them. - Repository templates are six complete Hubs for common internal roles, in the
templates/(opens in a new tab) folder of the GitHub repository. You copy one into place.
Bundled templates
hubzoid init my-hub # minimal (the default)
hubzoid init my-guide --template demo # guided tour
hubzoid init my-watchtower --template watchtower # workflow sampleEvery bundled template also gets a generated .env with a random bridge key and a MODEL, as described in the quickstart. An interactive hubzoid init uses the authenticated local CLI it finds, claude-local or codex-local, and asks once when both are usable. Otherwise MODEL is claude-local unless you pass --model.
| Template | Use it to | Main agent |
|---|---|---|
minimal | Learn the layout and replace each example with your own. | A brief, direct assistant that describes the Hub. |
demo | Take a guided tour of Hubzoid by chatting with it. | The Hubzoid Guide, which explains the framework by using each feature. |
watchtower | See a scheduled code workflow, its runs and its recovery. | Watchtower, an on-call assistant that answers questions about the workflow's reports. |
Minimal
One worked example of each file type, so the folder structure is obvious.
| Path | Example |
|---|---|
AGENTS.md | Starter instructions and three suggestions. |
agents/helper.md | An example sub-agent. |
skills/hello.md | A skill that calls the hello tool. |
knowledge/about.md | A page describing the Hub's purpose, for you to fill in. |
tools_local/hello.py | A @function_tool that returns a greeting. |
connectors/.mcp.json | An empty mcpServers map. |
schedule/example.md | A weekly task (enabled: false) that keeps knowledge/ in step with Git checkouts under raw_data/. |
evals/example.md | A check with a contains assertion and a ## Criteria section graded by a model. |
raw_data/README.md | Notes on searching the folder with grep_data. |
branding/ | Sample logo, favicon and splash images. |
Demo
The guided tour. The main agent, hubzoid-guide, answers questions such as "What is Hubzoid?" and "Build me an agent for daily standup notes".
| Path | Contents |
|---|---|
agents/builder.md | A sub-agent that drafts a minimal Hub for a one-line use case. |
skills/ | build-first-agent, explain-skills, find-the-docs and inspect-this-hub. |
knowledge/ | Six pages: what-is-hubzoid, welcome, agents-md-format, hub-folder-layout, three-agent-types and mcp-and-connectors. |
tools_local/word_count.py | A custom tool example. |
identity/access.csv.example | The roster format for WhatsApp and Telegram senders. |
The repository's demo-hub/ folder holds the same guided tour, ready to run from a clone.
Watchtower
A workflow-first sample. A code workflow checks service metrics every 15 minutes, decides in plain Python whether a service crossed a threshold, and asks the model only to explain the breach.
| Path | Contents |
|---|---|
workflows/watchtower/main.py | The @workflow(schedule="every 15 minutes") function and its steps: load_events, find_breaches, one hub.call_llm per new breach returning a validated Finding, and write_report. |
workflows/settings.yaml | Thresholds read with hub.setting("watchtower"): p95_ms: 800, error_rate: 0.02, window_minutes: 15, min_points: 3. |
raw_data/events/metrics.jsonl | One hour of sample metrics in which checkout slows down and fails after a deploy. |
raw_data/samples/broken.jsonl | A malformed file for the failure walkthrough. |
knowledge/watchtower.md | What the thresholds mean. |
AGENTS.md | The Watchtower chat agent, which reads output/watchtower/latest.md and the raw metrics. |
Run it once by hand, then read the report:
hubzoid init my-watchtower --template watchtower
cd my-watchtower
hubzoid schedule run . watchtower
cat output/watchtower/latest.mdA second run reports nothing new, because the workflow records each explained breach in hub.state. Locally, with sign-in off, runs act as admin@localhost, so that state belongs to that account. On a shared deployment, set run_as or HUBZOID_WORKFLOW_USER to choose the account, as described in code workflows. To let it run on its schedule, enable code workflows for this machine and start the Hub:
echo "HUBZOID_SCHEDULES=1" >> .env
hubzoid run .Each run then appears in the Console on the agent's Runs & schedules tab. To see a failure and its recovery, copy raw_data/samples/broken.jsonl into raw_data/events/, run the workflow again (it exits with code 1 and names the bad line), check hubzoid schedule status ., then remove the file and run it once more. The template's README.md has the full walkthrough, and code workflows explains each part.
Repository templates
Each repository template runs as it is on sample data. Where a real system (ledger, ERP, warehouse, alerting) would plug in, a placeholder tool in tools_local/ returns sample data and says so in its docstring. You replace the body of that function with a call to your system and keep its signature. Nothing else in the Hub changes.
| Template | Who uses it | Scheduled work | Placeholder tools |
|---|---|---|---|
Daily Reports (morning-briefing) | Leadership: managing director, finance head, operations head | daily-briefing on weekdays at 06:23, writes output/briefings/ | sales_snapshot, cash_position, ops_snapshot |
accounts-desk | Accounts team, finance head | nightly-bill-check Monday to Saturday at 20:41, writes output/accounts/ | find_purchase_order, search_bills, pending_bills, supplier_profile |
supplier-slip-check | Warehouse leads, operations head | overnight-reconciliation daily at 02:17, writes output/reconciliation/ | supplier_slips, ledger_receipts, post_to_team_chat |
stock-drift-watch | Inventory controller, warehouse leads | weekly-drift-scan on Mondays at 05:37 and monthly-slow-movers on the first of the month, write output/stock/ | locations, stock_snapshot, sku_movement |
company-qna | Everyone on the team | weekly-numbers-note on Mondays at 08:05, writes output/notes/ | list_metrics, metric |
it-ops-digest | On-call engineer, IT-ops lead | morning-digest daily at 07:03, and alert-intake when a webhook named alerting arrives | alerts_since, open_incidents, and a working runbook lookup over knowledge/runbooks.md |
Every repository template contains:
| Path | What it is |
|---|---|
AGENTS.md | Instructions with name, description, model: claude-local and four suggestions. |
knowledge/ | Two pages of sample company knowledge, such as thresholds, conventions or escalation rules. |
schedule/ | One or two markdown tasks with a cron or webhook trigger. |
evals/ | Two behavioral checks for hubzoid eval run. |
tools_local/ | The placeholder tools. |
connectors/.mcp.json | An empty mcpServers map. |
.env.example | Provider and surface variables to copy into .env. |
README.md | Who uses it, what it does, which surfaces to turn on and where the real systems plug in. |
Use a repository template
Repository templates are not part of the pip package. Daily Reports uses the repository's morning-briefing template folder. Clone the repository, copy that folder, and create its .env:
git clone https://github.com/hubzoid/hubzoid.git
cp -r hubzoid/templates/morning-briefing my-hub
cp my-hub/.env.example my-hub/.envThen edit my-hub/.env:
- Add
BRIDGE_API_KEYS=with a long random value, for example the output ofopenssl rand -hex 32.hubzoid initgenerates this line for bundled templates, andhubzoid doctorfails theauth.bridge_keyscheck until it is set. - Keep
MODEL=claude-localif theclaudeCLI is logged in, useMODEL=codex-localwith a local Codex login, or set another model and its key.MODELin.envwins over themodel:line inAGENTS.md.
Check the Hub, run a scheduled task by hand with tighter limits, and run its evals:
hubzoid doctor my-hub
hubzoid schedule list my-hub
hubzoid schedule run my-hub daily-briefing --timeout 300 --max-rounds 2
hubzoid eval run my-hub
hubzoid run my-hubEvery template works in the bundled web chat. To reach the team where they already are, add surfaces to the same process once their variables are set in .env:
hubzoid run my-hub --slack --telegram --whatsapp --webhookSee Slack, WhatsApp and Telegram and webhooks.
Make it yours
- Replace the pages in
knowledge/with your own figures, owners and rules. - Change the cron line in each
schedule/*.mdto fit your working day. - Replace the body of each placeholder tool with a call to the real system.
- Edit the evals so they assert facts from your own data.
- If a tool should be reachable only by some people, move its file to
restricted/and grant the permission. See restrict tools.
Next steps
Project structure
Every file and folder in a Hubzoid Hub, what each one holds, how Hubzoid discovers it, and which runtime folders to keep out of Git.
Architecture
How a request moves through Hubzoid, from chat surfaces and the edge to the bridge, agent runtimes, models, the workflow engine, databases and the Console.