Hub files

A Hub is one folder. Hubzoid reads the files below every time the Hub starts, and some on every call. Everything except the .env files and the runtime folders belongs in Git.

What hubzoid init writesCopy Anchor Link

hubzoid init my-hub writes every folder Hubzoid reads and a small starter for Kestrel & Oak, a fictional home-goods shop. An empty folder holds a .gitkeep so it stays in Git.

In an empty parent folder it also writes requirements.txt, .gitignore and README.md there, so the parent becomes a repository of Hubs. See the CLI reference.

File indexCopy Anchor Link

Other files, such as a README.md or a .gitignore, are not loaded by Hubzoid, so they can live in the Hub too.

Folder name variantsCopy Anchor Link

Folder names match without regard to case, and these variants are accepted. When two variants exist in one Hub, the first alphabetically is used and a warning is logged.

knowledge, restricted and identity have no variants.

AGENTS.mdCopy Anchor Link

The main agent. The body is the system prompt, used verbatim. Frontmatter is optional, so a plain Markdown file works. This is the starter's:

---
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.

A file with frontmatter but no body fails to load. tools: on the main agent has no effect: the main agent always has the full tool registry. AGENTS.md, sub-agents and skills may use {{settings.KEY}} for a declared setting.

Agent definitions: agents/Copy Anchor Link

Each sub-agent is either a folder, agents/<name>/AGENTS.md (or the first *.md in the folder), or a single file, agents/<name>.md. Hidden entries are skipped.

---
name: researcher
description: When the user wants a researched brief on a supplier or product.
model: claude-local/opus
tools: [web_search, http_get, read_knowledge]
---

Research the question with web_search and http_get, then write a short brief with sources.

Skill or delegate. A sub-agent becomes a delegate only when its model: differs from the Hub's model on the same engine, for example claude-local/opus in a claude-local Hub, a different Codex model in a codex-local Hub, or a different LiteLLM id in a LiteLLM Hub. A delegate runs on its own model in its own context and returns its answer to the main agent, which stays in control. On the OpenAI Agents SDK and Codex runtimes the main agent calls it as a tool named handover_<name>. On claude-local it runs as a Claude subagent. Every other sub-agent (no model:, the same model, or a different engine) is loaded inline as a skill, and its tools: list is ignored with a warning. A delegate whose model is missing its provider key falls back to a skill so the Hub still starts.

Isolated agents (stations). isolated: true makes the sub-agent a station: an agent with one job that a work-item workflow calls for one stage. It gets only its own instructions and exactly the tools it lists, never the main agent's conversation, skills or knowledge.

Check stations with hubzoid stations validate. See the SDK guide stations (opens in a new tab).

Skills: skills/Copy Anchor Link

Each skill is skills/<name>/SKILL.md (also skill.md, Skill.md or the first *.md in the folder) or a single file, skills/<name>.md.

---
name: weekly-summary
description: Three-bullet summary of the week's orders for the operations lead.
---

1. Call list_knowledge and read the house rules.
2. Pull the week's numbers with the order tools.
3. Reply with three bullets and one risk to watch.

The agent sees each skill's name and description and loads the body with load_skill only when it needs it. Other frontmatter keys are ignored. Supporting files in a skill folder are not loaded automatically. Name them by their path from the Hub root in the skill body, and the agent reads them with read_file.

Name collisions resolve in this order: skills/ first, then sub-agents loaded as skills, then Hubzoid's built-in dashboard skill (chat surfaces only). A skill file with no body or with frontmatter that cannot be parsed stops the Hub from building.

Knowledge: knowledge/Copy Anchor Link

Every *.md under knowledge/, including subfolders, is one document. Hidden files and _index.md are skipped.

# House rules

- **Refunds.** A customer can return an unused item within 30 days of
  delivery for a full refund. After 30 days we offer store credit or a
  repair, not a refund.
- **Large orders.** An order over $500 needs a manager's approval before it
  ships.
- **Support hours.** Support answers from 09:00 to 18:00 UTC, Monday to Friday.

Frontmatter is optional. The knowledge tools read the folder live, so an edited or added document is visible on the next call without a restart. A file with broken frontmatter is skipped with a warning and the rest still load.

knowledge/_learned/<topic>.md holds what the remember tool saved for everyone. remember is a proposal that a Hub manager applies, and it is offered only when browser editing is on. See memory and history.

Tools: tools_local/ and restricted/Copy Anchor Link

Every *.py file in these folders is imported when the Hub builds, and every module-level FunctionTool (a function decorated with @function_tool from the agents package) becomes a tool. Files whose names start with _ are skipped.

• A tools_local/ tool with the same name as a built-in tool replaces the built-in.
• A restricted/<capability>.py tool requires the capability named by the file stem. Every tool in the file shares it, and Settings lists it under restricted tools so you can grant it. It wins over any tool of the same name and is guarded before every call. identity/permissions.yaml can label it.
• restricted/.env holds the secrets those tools read. File tools refuse every path under restricted/.

See tools and connectors and restrict tools.

Connectors: connectors/Copy Anchor Link

connectors/.mcp.jsonCopy Anchor Link

MCP servers that serve everyone who uses the agent, in the mcpServers shape. connectors/mcp.json (no leading dot) is read when .mcp.json is absent. Settings lists these servers read-only under the agent's Connectors, with their names and any missing settings, never values.

{
  "mcpServers": {
    "tickets": {
      "transport": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${TICKETS_TOKEN}" }
    }
  }
}

${NAME} in any string is replaced with that environment variable after .env is loaded. Names use uppercase letters, digits and underscores. With HUBZOID_BROWSER=true, a playwright server is added automatically, and an entry of your own with that name replaces it. Invalid JSON stops the Hub from building.

Remote connectorsCopy Anchor Link

Remote MCP servers that each person signs in to, or that use one company key. They live in the deployment folder (the Hub folder for a deployment of one). Settings reads them, and writes them only when browser editing is on. Each person connects their own account in Settings.

version: 1
name: Tickets
url: https://mcp.example.com/mcp
sign_in: oauth
scopes: [tickets.read]
tools: [list_tickets, get_ticket]
hubs: [my-hub]
enabled: true

Channels: channels/Copy Anchor Link

One YAML file per channel connection, channels/<id>.yaml. Slack (provider: slack_assistant), WhatsApp (whatsapp_inbound), Telegram (telegram) and generic webhooks (webhook) each turn on with a file of four keys: version: 1, id, provider and enabled: true. Their secrets stay in .env. Check a file with hubzoid channels validate and see its status with hubzoid channels list. See Slack and WhatsApp and Telegram.

Scheduled tasks: schedule/Copy Anchor Link

One Markdown file per task. The file name (letters, digits, ., _ and -, starting with a letter or digit) is the task name. The body is the agent's instructions, or optional notes for a run: script task.

---
schedule: "7 6 * * 1-5"
write: ["output/reports"]
publish_artifacts: true
---

Write yesterday's order summary to output/reports/<date>.md and publish it as a report.

The full behaviour, including rounds, catch-up and webhook inboxes, is in markdown tasks.

Workflows: workflows/Copy Anchor Link

Each code workflow lives in workflows/<name>/. Every *.py file directly in that folder whose name does not start with _ is imported, and each function decorated with @workflow is registered under its function name. Subfolders, such as a package of helper modules, are not imported as workflows. hubzoid new workflow scaffolds one. The API is in the workflow API reference.

workflows/settings.yamlCopy Anchor Link

Optional. Workflows read any top-level key with hub.setting("<key>"), and the keys below configure the engine, webhooks, alerts, reports and email.

agent_max_attempts: 1          # tries for a failed hub.call_agent step. 1 means no retry.
max_concurrent_workflows: 2    # cap on code workflows on the shared queue
workflow_timeout: 30m          # default run deadline

webhooks:
  ticket-updated:
    verify: header
    header: X-Webhook-Secret
    event_key: "{ticket.id}:{ticket.modifiedTime}"

alerts:
  to:
    - webhook: ALERT_WEBHOOK_URL   # an environment variable that holds the URL
    - email: ops@example.com
  cooldown: 1h

series_keep: 50
email_lists:
  leads: [asha@example.com, ravi@example.com]

personal_schedules:
  min_interval: 1h
  per_person: 10

stock_drift:                   # your own key, read with hub.setting("stock_drift")
  threshold_pct: 5

Each entry under webhooks: is served by the Hub's bridge at /webhooks/<hub>/<name>, and its secret is the environment variable WEBHOOK_SECRET_<NAME>, with the name upper-cased and hyphens turned into underscores. Names use lowercase letters, digits, - and _, up to 64 characters. whatsapp, telegram and the Hub's WEBHOOK_INBOUND_NAME (default webhook) are taken by the inbound receiver and refused.

The file is validated when the bridge starts. A mistake, such as invalid YAML, an unknown verification or an empty alert destination, turns the workflow engine off for that Hub and records the error in workflow health, which hubzoid doctor reports as scheduler.health. Chat keeps running, and the Hub's webhook URLs answer 503 until the file is fixed and the bridge restarts. See code workflows and webhooks.

workflows/access.yamlCopy Anchor Link

Optional. Who may run, schedule, edit, approve and see each workflow. Check it with hubzoid workflow-access validate, preview the change with hubzoid workflow-access diff and apply it with hubzoid workflow-access apply. See the CLI reference.

Evals: evals/Copy Anchor Link

One Markdown file per case. The case id is its path under evals/ without .md. Files and folders starting with _ or ., and evals/fixtures/, are skipped.

---
contains: ["house-rules"]
---
## Prompt
A customer wants a refund 40 days after delivery. What can we offer?

## Criteria
Follows the refund rule in knowledge/house-rules.md for that many days,
and names house-rules.md as its source.

Every frontmatter key is optional: schedule, tags, expect_tools, forbid_tools, expect_tool_args, contains, not_contains, timeout (1 to 3600 seconds, default 120), threshold (the judge's pass mark out of 10, default 7), enabled, run_as, and fake_tools, real_tools and allow_real_mcp for fake tool results. Any other key is an error.

The body holds a ## Prompt section and an optional ## Criteria section, which turns the judge on. A conversation uses ## Turn 1, ## Turn 2 and so on instead of ## Prompt. A body with no headings is the prompt. See evals.

Identity: identity/Copy Anchor Link

Who a WhatsApp or Telegram sender is comes first from the phone number recorded on a person in Settings. A Hub can add its own live lookup, for example in a CRM. A lookup only says who someone is. What they may do is decided by their grants in Settings.

identity/access.csv is no longer read. Put phone numbers on people in Settings, and grant who may use a channel there. A Hub that still has the file gets a warning.

identity/access.pyCopy Anchor Link

A function-backed lookup, such as a CRM.

def resolve(surface: str, handle: str) -> dict | None:
    """Return {"email": ..., "groups": [...]} for a phone or chat handle, or None."""
    ...

def groups_for_email(email: str) -> list[str]:
    """Optional. Group labels for a web or MCP caller, looked up by email."""
    ...

groups_for_email is optional, and without it the file never receives email lookups. Groups are labels the agent can see as context, and they grant nothing. Results are cached for 60 seconds. An exception in either function resolves to no one and no groups rather than failing the request. On WhatsApp and Telegram, a sender whose number neither Settings nor the lookup knows is refused.

identity/permissions.yamlCopy Anchor Link

Labels for the capabilities of restricted/*.py files in Settings, read without running any tool code. An entry that names a built-in capability, such as use_hub, manage_access or curator, is ignored with a warning.

finance:
  label: Finance reports
  description: Read margins and receivables from the accounting system.
  sensitive: true

Access concepts are covered in identity and access.

Branding: branding/Copy Anchor Link

The agent's avatar. A Hub's branding/logo.svg, logo.png or logo.webp, then favicon.svg or favicon.png, is its agent's avatar in the web app. The first file present wins. Names match without regard to case.

The deployment's brand (name, logos, favicon, sign-in text, links, terms) is the brand: section of hubzoid.yaml, with its files under branding/ next to it. Colours, fonts and corner radius go in branding/theme.json. Until a deployment has a brand: section, a branding.yaml there is read instead. Check the brand with hubzoid branding validate, and turn an older branding/ folder into branding.yaml with hubzoid branding import-legacy.

custom.css is no longer served. The brand's presentation.decorative_css can style three brand slots only. See the SDK guide branding (opens in a new tab).

Other files at the Hub rootCopy Anchor Link

All optional. A Hub without them behaves as before.

A value from hub.settings.yaml gives way to the environment variable a setting names in env:, and a missing value falls back to the default. See the SDK guides for approvals (opens in a new tab), usage limits (opens in a new tab), work items (opens in a new tab), Hub settings (opens in a new tab), cards (opens in a new tab) and sandboxes (opens in a new tab).

Runtime foldersCopy Anchor Link

Hubzoid creates these while it runs, under the Hub folder or under HUBZOID_DATA_DIR when set. Keep them out of Git and include them in backups with hubzoid backup.

Next stepsCopy Anchor Link