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.
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. Keep the folder in Git, except the secrets and runtime folders listed at the end of this page.
The complete layout
What each part does
| Path | What it holds | How Hubzoid uses it |
|---|---|---|
AGENTS.md | The main agent. YAML frontmatter plus a Markdown body. | The body becomes the system prompt. Required at the Hub root, with exactly this file name. |
.env | Model, keys and settings for this Hub. | Loaded at start and wins over the shell environment. Never commit it. |
agents/ | Sub-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. |
skills/ | Playbooks, as skills/<name>.md or skills/<name>/SKILL.md. | Listed by name and description in the system prompt, loaded on demand with load_skill(name). |
knowledge/ | Reference documents, any *.md in the folder or its subfolders. | Listed in the system prompt, read on demand with read_knowledge(name). Read live from disk. |
knowledge/_learned/ | Documents written by the remember tool. | Ordinary knowledge named learned/<slug>. See memory and history. |
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. |
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. |
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. |
schedule/ | Markdown tasks, one *.md per job, with a cron or webhook trigger in frontmatter. | Run on the workflow engine by the Hub's own agent, or as a command when the task sets run:. See markdown tasks. |
workflows/ | Code workflows, as workflows/<name>/*.py with a @workflow function, and an optional workflows/settings.yaml. | Imported and scheduled on the workflow engine. hub.setting(...) reads settings.yaml. See code workflows. |
identity/ | access.csv or access.py (a roster of people by phone and email), and permissions.yaml (labels for permissions). | The roster admits WhatsApp and Telegram senders and adds groups. The labels appear in the Console. See identity and access. |
raw_data/ | Unstructured material: exports, document dumps, code checkouts. | Searched with grep_data, read with read_file. No indexing step. |
branding/ | logo.*, favicon.*, splash.* and an optional custom.css. | Copied into the chat app at every start. |
evals/ | Behavioral checks, one *.md per case. | Run with hubzoid eval run. See evals. |
A scaffolded Hub also has .gitignore. Hub files is the field-by-field reference for every file format on this page.
AGENTS.md
The main agent is a Markdown file. 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.
---
name: accounts-desk
description: Checks supplier bills against purchase orders and drafts entries for review.
suggestions:
- Which pending bills need a decision
- Is this bill a duplicate
---
You are the accounts desk agent for the finance team.
Check each bill against its purchase order before you draft an entry.
Quote the tolerance from knowledge/matching-rules.md when a line does not match.Prop
Type
Sub-agent 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.
Skills and knowledge files
Skills and knowledge are both Markdown with a small frontmatter block. The difference is how the agent uses them: a skill is a procedure the agent follows, and a knowledge document is reference material it quotes or reasons from.
---
name: weekly-report
description: Builds the weekly operations 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.| File | Frontmatter fields | When a field is missing |
|---|---|---|
| Skill | name, description | The name comes from the folder (for SKILL.md) or the file name, and a generic description is used. |
| Knowledge | name, description, optional keywords list | The name is the file name without .md, and a generic description is used. |
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.
Folder names
Folder names are matched without regard to case, and several spellings are accepted. If two spellings exist in the same Hub, the first in alphabetical order is used and a warning is logged.
| Folder | Accepted names |
|---|---|
agents | agents, agent |
skills | skills, skill |
knowledge | knowledge |
tools_local | tools_local, tool_local, tools, local_tools |
connectors | connectors, connector |
schedule | schedule, schedules, scheduled |
workflows | workflows, workflow |
evals | evals, eval, evaluations |
raw_data | raw_data, raw-data, rawdata |
restricted | restricted |
identity | identity |
output | output, outputs |
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 scaffolded .gitignore excludes .hubzoid/, .openwebui-data/, output/ and .env. Add .inbound/ to it if the Hub receives webhooks.
| Path | Written by | Contents |
|---|---|---|
.hubzoid/ | Hubzoid | hub.db (Hubzoid's tables on a single Hub), dbos.db (workflow runs and checkpoints), artifact_secret (signs download links), chats/<chat_id>/ (uploads and files the agent saved), schedule/<task>/ (task state and run logs) and eval results. |
.openwebui-data/ | The chat app | Accounts, sessions and chats in webui.db, plus the chat app log. |
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, under .inbound/webhooks/<name>/. |
Under hubzoid gateway, accounts and the shared access database live in the gateway's data folder instead. 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, ports and chat database. To run several Hubs behind one sign-in, use the gateway.