---
title: Templates
description: 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.
canonical_url: https://hubzoid.com/docs/getting-started/templates
last_updated: 2026-09-27
---

# 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 init` scaffolds them.
- **Repository templates** are six complete Hubs for common internal roles, in the [`templates/`](https://github.com/hubzoid/hubzoid/blob/main/templates/README.md) folder of the GitHub repository. You copy one into place.

## Bundled templates

```bash
hubzoid init my-hub                             # minimal (the default)
hubzoid init my-guide --template demo           # guided tour
hubzoid init my-watchtower --template watchtower  # workflow sample
```

Every bundled template also gets a generated `.env` with a random bridge key and a `MODEL`, as described in the [quickstart](https://hubzoid.com/docs/getting-started/quickstart#create-a-hub). 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:

```bash
hubzoid init my-watchtower --template watchtower
cd my-watchtower
hubzoid schedule run . watchtower
cat output/watchtower/latest.md
```

A 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](https://hubzoid.com/docs/guides/code-workflows#access). To let it run on its schedule, enable code workflows for this machine and start the Hub:

```bash
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](https://hubzoid.com/docs/guides/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`:

```bash
git clone https://github.com/hubzoid/hubzoid.git
cp -r hubzoid/templates/morning-briefing my-hub
cp my-hub/.env.example my-hub/.env
```

Then edit `my-hub/.env`:

- Add `BRIDGE_API_KEYS=` with a long random value, for example the output of `openssl rand -hex 32`. `hubzoid init` generates this line for bundled templates, and `hubzoid doctor` fails the `auth.bridge_keys` check until it is set.
- Keep `MODEL=claude-local` if the `claude` CLI is logged in, use `MODEL=codex-local` with a local Codex login, or set another model and its key. `MODEL` in `.env` wins over the `model:` line in `AGENTS.md`.

Check the Hub, run a scheduled task by hand with tighter limits, and run its evals:

```bash
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-hub
```

Every 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`:

```bash
hubzoid run my-hub --slack --telegram --whatsapp --webhook
```

See [Slack](https://hubzoid.com/docs/chat/slack), [WhatsApp and Telegram](https://hubzoid.com/docs/chat/whatsapp-and-telegram) and [webhooks](https://hubzoid.com/docs/guides/webhooks).

### Make it yours

1. Replace the pages in `knowledge/` with your own figures, owners and rules.
2. Change the cron line in each `schedule/*.md` to fit your working day.
3. Replace the body of each placeholder tool with a call to the real system.
4. Edit the evals so they assert facts from your own data.
5. If a tool should be reachable only by some people, move its file to `restricted/` and grant the permission. See [restrict tools](https://hubzoid.com/docs/guides/restrict-tools).

## Next steps

- [Project structure](https://hubzoid.com/docs/getting-started/project-structure): Every file and folder a template uses.
- [Markdown tasks](https://hubzoid.com/docs/guides/markdown-tasks): How the scheduled tasks in these templates run.
- [Evals](https://hubzoid.com/docs/guides/evals): Write and run behavioral checks for a Hub.