--- title: Project structure description: 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. canonical_url: https://hubzoid.com/docs/getting-started/project-structure last_updated: 2026-09-27 --- # 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 ```text my-hub/ AGENTS.md .env .gitignore agents/ helper.md researcher/ AGENTS.md skills/ hello.md weekly-report/ SKILL.md knowledge/ about.md _learned/ billing-edge-cases.md tools_local/ hello.py restricted/ ledger.py .env connectors/ .mcp.json schedule/ example.md workflows/ settings.yaml daily-report/ main.py identity/ access.csv permissions.yaml raw_data/ README.md branding/ logo.svg favicon.svg splash.png evals/ example.md output/ .hubzoid/ .openwebui-data/ ``` ## 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/.md` or `agents//AGENTS.md`. | Loaded inline as skills, or run on their own model as delegates. See [agents and models](https://hubzoid.com/docs/concepts/agents-and-models). | | `skills/` | Playbooks, as `skills/.md` or `skills//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/`. See [memory and history](https://hubzoid.com/docs/concepts/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](https://hubzoid.com/docs/guides/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](https://hubzoid.com/docs/guides/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](https://hubzoid.com/docs/guides/markdown-tasks). | | `workflows/` | Code workflows, as `workflows//*.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](https://hubzoid.com/docs/guides/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](https://hubzoid.com/docs/concepts/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](https://hubzoid.com/docs/guides/evals). | A scaffolded Hub also has `.gitignore`. [Hub files](https://hubzoid.com/docs/reference/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. ```markdown title="AGENTS.md" --- 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. ``` | Name | Type | Default | Description | | --- | --- | --- | --- | | `name` | `string` | `Hub folder name` | Agent identifier, also shown as the agent name in the chat app. | | `description` | `string` | `First non-heading line of the body` | One-line summary of the agent. | | `model` | `string` | | Model id used when .env does not set MODEL, for example claude-local or openai/gpt-4o-mini. | | `suggestions` | `string[]` | | Prompts shown as buttons on the empty chat screen. | | `auto_addendum` | `boolean` | `true` | Set to false to stop Hubzoid appending its runtime section (knowledge and skill menus, tool guidance) to the system prompt. | | `mcp_instructions` | `string` | | Text sent to MCP clients when they connect, instead of the AGENTS.md body. | 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. ```markdown title="skills/weekly-report/SKILL.md" --- 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//` (uploads and files the agent saved), `schedule//` (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//`. | Under `hubzoid gateway`, accounts and the shared access database live in the gateway's data folder instead. See [architecture](https://hubzoid.com/docs/concepts/architecture#databases). ## 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: ```bash 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/ only ``` Each Hub keeps its own `.env`, ports and chat database. To run several Hubs behind one sign-in, use the [gateway](https://hubzoid.com/docs/deploy/gateway). ## Next steps - [The Hub](https://hubzoid.com/docs/concepts/hub): How these files become the context for every run. - [Templates](https://hubzoid.com/docs/getting-started/templates): Complete Hubs to copy and adapt. - [Hub files reference](https://hubzoid.com/docs/reference/hub-files): Every frontmatter field and file format.