Project structure
What hubzoid init writes, every folder Hubzoid reads, the files you add later, and which runtime folders stay out of Git.
A Hub is one folder. Only AGENTS.md is required. Every other folder is optional and is picked up when it exists, so a Hub can start as a single file and grow as the work does.
This page starts with the folder hubzoid init my-hub writes, then explains each part Hubzoid reads. Keep the whole folder in Git, except the secrets and runtime folders listed at the end.
What hubzoid init writes
hubzoid init my-hub| File | What it holds |
|---|---|
AGENTS.md | The assistant's job: the team assistant for Kestrel & Oak, a fictional home-goods shop, with three suggested questions. |
knowledge/house-rules.md | Three house rules to ask about and edit: refunds within 30 days of delivery, a manager's approval for orders over $500, and support hours. |
evals/refund-window.md | One check that the refund answer follows the rules and names house-rules.md. |
connectors/.mcp.json | An empty mcpServers map, where MCP servers go. |
.env | The model (MODEL=claude-local unless init found or saved another) and a random BRIDGE_API_KEYS value. Readable only by you. Never commit it. |
.gitignore | Keeps .env, output/, .hubzoid/ and Python caches out of Git. |
README.md | What each folder is for, and how to try the starter. |
The other six folders are empty and ready for your files. Each holds a .gitkeep so Git keeps it. init writes seven files in all.
What init writes around the Hub in an empty folder
In an empty parent folder, init also writes an agents repository around the Hub: requirements.txt (pinned to the installed Hubzoid), .gitignore and README.md. Running init again in the same parent adds another Hub and leaves those files alone. See several Hubs in one repository.
Folders Hubzoid reads
| Path | What goes in it | How Hubzoid uses it |
|---|---|---|
AGENTS.md | The main agent. Optional YAML frontmatter plus a Markdown body. | The body becomes the system prompt. Required at the Hub root, with exactly this name. See AGENTS.md. |
knowledge/ | What the assistant knows: rules, policies, notes. Any *.md in the folder or its subfolders. | Listed in the system prompt and read on demand with read_knowledge. Read live from disk. |
skills/ | Procedures, as skills/<name>.md or skills/<name>/SKILL.md. | Listed by name and description, loaded on demand with load_skill. |
agents/ | Specialist agents, as agents/<name>.md or agents/<name>/AGENTS.md. | Loaded inline as skills, or run on their own model as delegates. See agents and models. |
tools_local/ | Python files with @function_tool functions. | Every module-level tool is added to the agent. A local tool with the same name as a built-in replaces it. |
connectors/.mcp.json | MCP servers the agent can use, in the mcpServers format. connectors/mcp.json also works. | ${VAR} references are filled from the environment at start. See tools and connectors. |
workflows/ | Code workflows, as workflows/<name>/*.py with a @workflow function, plus an optional workflows/settings.yaml. | Run on the workflow engine on a schedule, from a webhook, on request or from chat. hubzoid new workflow <name> my-hub writes one. See code workflows. |
schedule/ | Markdown tasks, one *.md per job, with a cron or webhook trigger in frontmatter. | Run by the Hub's own agent, or as a command when the task sets run:. See markdown tasks. |
evals/ | Checks that answers stay right, one *.md per case. | Run with hubzoid eval run my-hub. See evals. |
raw_data/ | Files the assistant can search and read: exports, document dumps, code checkouts. | Searched with grep_data, read with read_file. No indexing step. |
AGENTS.md
The main agent is a Markdown file. This is the one the starter writes:
---
description: A starter assistant for Kestrel & Oak, a fictional home-goods shop. Make it yours.
suggestions:
- A customer wants a refund 40 days after delivery. What can we offer?
- Who has to approve a $650 order?
- When is support open?
---
You are the team assistant for Kestrel & Oak, a fictional home-goods shop
used as Hubzoid's starter. Answer from the files in `knowledge/` and name the
file you used. If they do not answer the question, say so instead of
guessing. Keep answers short.Frontmatter is optional. Without it, the name is the Hub folder name and the description is the first line of the body that is not a heading. These are the fields the main agent reads.
Every frontmatter field of AGENTS.md
Prop
Type
Files in agents/ accept name, description and model, plus tools, a list of tool names the sub-agent may call when it runs as a delegate. Hub files is the field-by-field reference.
If your project already has an AGENTS.md for coding agents, put the Hub in a subfolder so the two prompts stay separate.
Skills and knowledge files
Both are Markdown with a small frontmatter block. A skill is a procedure the agent follows. A knowledge document is reference material it quotes or reasons from.
---
name: weekly-report
description: Builds the weekly report. Use when someone asks for this week's numbers.
---
1. Read knowledge/report-format.md.
2. Collect the figures with the sales_snapshot tool.
3. Save the report with write_artifact and share the link.Both fields are optional. Without them, the name comes from the folder (for SKILL.md) or the file name, and a generic description is used. Knowledge files may also list keywords.
Which knowledge files are skipped
In knowledge/, files whose names start with a dot and files named _index.md are skipped. One unreadable knowledge file is skipped with a warning, and the rest still load.
Files you add later
These are not in the starter. Add them when the Hub needs them.
| Path | What it holds | How Hubzoid uses it |
|---|---|---|
restricted/ | Python tools that need a permission, plus restricted/.env for their secrets. | The file name is the permission. Calls are checked and recorded. The agent's file tools cannot read this folder. See restrict tools. |
channels/ | One YAML file per channel, such as slack-assistant.yaml, with version, id, provider and enabled. | A file with enabled: true starts that channel with the Hub. Its secrets stay in .env. See Slack and WhatsApp and Telegram. |
identity/permissions.yaml | Labels for the Hub's restricted capabilities. | The labels appear in Settings. See identity and access. |
identity/access.py | An optional resolve(surface, handle) function that looks people up in your own system. | Names WhatsApp, Telegram and webhook senders. It grants nothing. |
branding/ | Logo and favicon images, and an optional theme.json for colours and fonts. | The brand: section of hubzoid.yaml points at these files. |
settings.yaml, hub.settings.yaml | Settings the Hub declares, and their values. | Filled into instructions as {{settings.KEY}}. hubzoid hub settings lists them and hubzoid hub configure --check validates the values. |
knowledge/_learned/ | Knowledge a person approved from the agent's remember proposals. | Read like any other knowledge. Written only when changing agent files from the browser is turned on, which is Beta and off by default. See memory and history. |
identity/access.csv is no longer read
Phone numbers now live on people in Settings, and who may use a channel is a grant there. A Hub that still has identity/access.csv gets a warning that says what to do instead.
Folder names
Folder names are matched without regard to case, and singular and plural spellings both work, so Skills/, skill/ and skills/ are the same folder. If two spellings exist in the same Hub, the first in alphabetical order is used and a warning is logged. Hub files lists every accepted spelling.
In tools_local/, restricted/, workflows/ and evals/, files whose names start with an underscore are skipped, so you can keep helpers and drafts beside real files.
Runtime folders
Hubzoid writes these while the Hub runs. They stay inside the Hub folder, so hubzoid backup finds them and deleting the folder removes them. The starter's .gitignore already excludes .hubzoid/, output/ and .env. Add .inbound/ if the Hub receives webhooks.
| Path | Written by | Contents |
|---|---|---|
.hubzoid/ | Hubzoid | hub.db (accounts, sessions, conversations, grants, usage and workflow state for a single Hub), dbos.db (workflow runs and checkpoints), secret.key (the deployment key, which encrypts stored connector credentials), artifact_secret (signs download links), chat uploads and saved files, published reports, schedule state and eval results. |
output/ | Agents and tasks | Files saved outside a chat and reports written by scheduled work. |
.inbound/ | Inbound surfaces | Webhook deliveries waiting for a task, one JSON file each. |
Where state lives when several Hubs run together
When several Hubs run together, accounts, conversations and the shared access database live in the deployment's state folder instead (.hubzoid/ next to hubzoid.yaml, or --data-dir), and each Hub keeps its own dbos.db. See architecture.
Several Hubs in one repository
Run hubzoid init more than once in the same folder to build an agents repository one Hub at a time:
mkdir my-agents && cd my-agents
hubzoid init finance-agent # writes requirements.txt, .gitignore, README.md and finance-agent/
hubzoid init operations-agent # writes operations-agent/ onlyEach Hub keeps its own .env. To run several Hubs behind one sign-in, start them together with hubzoid run finance-agent operations-agent, or list them in a hubzoid.yaml in this folder and run hubzoid run. See running several Hubs.