Hub files

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

LayoutCopy Anchor Link

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.

---
name: ops-desk
description: Answers stock and order questions for the operations team.
model: claude-local/sonnet
suggestions:
  - Which items are below reorder level?
  - Summarize yesterday's orders
mcp_instructions: |
  Use read_knowledge for policy questions and stock_level for live counts.
---

You help the operations team of a home goods retailer with four stock locations.
Answer from knowledge files and tools. Never guess a stock count.

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.

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

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 reporting policy.
2. Pull the week's numbers with the stock and 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 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.

---
name: returns-policy
description: Return windows, exceptions and who approves refunds.
keywords: [returns, refunds, exchange]
---

Returns are accepted within 14 days with the original receipt.

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. Documents saved with the remember tool live in knowledge/_learned/ with the name learned/<topic>. 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/<permission>.py tool requires the permission named by the file stem. It wins over any tool of the same name and is guarded before every call.
• restricted/.env holds the secrets those tools read. File tools refuse every path under restricted/.

See tools and connectors and restrict tools.

Connectors: connectors/.mcp.jsonCopy Anchor Link

External MCP servers, in the mcpServers shape. connectors/mcp.json (no leading dot) is read when .mcp.json is absent.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GH_TOKEN}" }
    },
    "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.

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.

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 there whose name does not start with _ is imported, and each function decorated with @workflow is registered under its function name. hubzoid new workflow scaffolds one. The API is in the workflow API reference.

workflows/settings.yaml is optional. Workflows read any top-level key with hub.setting("<key>"), and two keys configure the engine:

agent_max_attempts: 1         # tries for a failed hub.call_agent step. 1 means no retry.
max_concurrent_workflows: 2   # hub-wide cap on code workflows running at once. Unset means no cap.
stock_drift:
  threshold_pct: 5

Evals: evals/Copy Anchor Link

One Markdown file per case. The file name is the case name. Files starting with _ or . are skipped. Frontmatter keys are schedule, tags, expect_tools, forbid_tools, contains, not_contains, timeout, threshold and enabled, and any other key is an error. The body holds a ## Prompt section and an optional ## Criteria section. See evals.

Identity: identity/Copy Anchor Link

identity/access.csvCopy Anchor Link

A roster of people. The header row names the columns. phone, email and groups have meaning to Hubzoid, and any other column is kept as context on the person's record.

phone,email,groups,center
919800000001,meera@example.com,coordinator,north
919800000002,arjun@example.com,coordinator;finance,south

• phone identifies WhatsApp and Telegram senders. Formatting is normalized, so a prettified number matches.
• email links the row to the person's web chat and MCP identity, and is lowercased.
• groups are separated by ; or ,. Rows that share an email combine their groups.

The file reloads when it changes on disk, with no restart. An unreadable or half-written file resolves to no groups, never to old ones, so save it by writing a new file and renaming it into place. On WhatsApp and Telegram the roster is the allowlist: a sender whose number is not listed is refused. For web chat and MCP callers the roster only adds groups.

identity/access.pyCopy Anchor Link

A function-backed roster for live lookups, such as a CRM. It wins over access.csv when both exist.

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. Groups for a web chat or MCP caller, looked up by email."""
    ...

groups_for_email is optional, and without it the file never receives email lookups. Results of groups_for_email are cached for 60 seconds. An exception in either function denies rather than failing the request.

identity/permissions.yamlCopy Anchor Link

Labels for the permissions the Console shows. The Console lists use_hub, manage_access and one permission per restricted/*.py file, and this file adds text to them without running any tool code.

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

Files copied into the web chat on every start. Names match without regard to case.

When branding/ holds any file, Open WebUI's own name suffix and branding are replaced, unless HUBZOID_KEEP_OWUI_SUFFIX=true. In a gateway, a Hub's logo or favicon raster (PNG, WebP, JPEG or GIF) becomes its avatar in the model picker.

Runtime foldersCopy Anchor Link

Hubzoid creates these while it runs. Keep them out of Git and include them in backups with hubzoid backup.

Next stepsCopy Anchor Link

Read this page as Markdown