Configuration reference

Every setting Hubzoid reads: the deployment file hubzoid.yaml, then environment variables grouped by area. Most Hubs set only the model in <hub>/.env. Everything else has a working default.

Where each setting livesCopy Anchor Link

A Hub's own declared settings (settings.yaml, hub.settings.yaml) and files such as hitl.yaml and budgets.yaml are described in Hub files.

hubzoid.yamlCopy Anchor Link

The deployment file. It sits in the deployment folder: the folder that holds the Hub folders, or the Hub folder for a deployment of one. hubzoid run with no arguments runs it.

version: 1
public_url: https://hub.example.com
sign_in: true
owner: sam@example.com
hubs:
  - my-hub
  - finance/finance-hub

An unknown key, a wrong type or a Hub folder without AGENTS.md stops the start, naming the file, key and line. The file holds policy that must never fall back to an open default. A key set both here and in its environment variable, with different values, also stops the start and names both.

Browser editing (Beta)Copy Anchor Link

An agent's instructions, skills, connectors, channels, approval rules, usage limits and settings are files. By default people read them in Settings and change them in the files, or ask Claude Code or Codex. With browser editing off:

• Proposing and approving Hub changes in Settings or chat answers that it is off.
• The remember and propose_hub_change tools answer that it is off and say where to change the file.
• Saving connectors, channels, settings, approval rules and budgets in Settings is read-only, with a note on where to change them.

Turn it on with in_app_editing: true in hubzoid.yaml, or HUBZOID_IN_APP_EDITING=true in one Hub's .env. Files that come from an image (HUBZOID_DATA_DIR set) are never written from the browser. The CLI's apply commands and hubzoid hub-changes keep working either way. Workflow permissions and stored secrets live in the database and stay editable.

Chat defaultsCopy Anchor Link

The chat: section holds the keys of the chat configuration without version:. Settings → Organization shows them read-only. Every agent reads a change within a few seconds. hubzoid chat config schema prints every key with its default.

chat:
  presentation:
    appearance:
      default_mode: dark
  models:
    allow_choice: true
    default_ref: sonnet
    catalog:
      sonnet: {label: Claude Sonnet, model: sonnet}
      haiku: {label: Claude Haiku, model: haiku}

The server refuses a model that is not in the catalog. A model runs on the agent's own runtime, so list models of that runtime: a Claude agent cannot answer with a Codex model. Ratings settings live under feedback. Without a chat: section, chat/config.yaml in the deployment folder is read.

Apps: chat inside your appCopy Anchor Link

Each entry under apps: registers one app that embeds a Hubzoid agent's chat through the AG-UI endpoint /api/agui. The key is the app's client id. Make its secret and a ready entry with hubzoid embed secret.

apps:
  erpnext:
    name: Kestrel & Oak ERP
    secret_ref: secret:deployment/app-erpnext
    origins: [https://erp.example.com]
    access:
      agents: [my-hub]
      tools: [app_lookup, read_knowledge]
    token_to: [app_lookup]
    max_lifetime: 3600

No Hubzoid account is created for people who come from an app. Their chats are kept under a private id made from the app and their user id. Without a hubzoid.yaml, put the same section in apps.yaml in the deployment folder. The SDK guide chat inside your app (opens in a new tab) has the server and page code.

How settings loadCopy Anchor Link

• <hub>/.env is loaded whenever a command builds or serves the Hub. Its values win over variables already set in your shell. A deployment that should take its values from the process environment instead (a systemd EnvironmentFile, a container platform) ships no .env.
• <hub>/restricted/.env is loaded next, also overriding. It holds secrets that restricted tools read from the environment. The file tools refuse every path under restricted/, so the model cannot read these values. The claude CLI and the MCP servers it starts do not inherit them, nor Hubzoid's own service secrets.
• Booleans are on when set to 1, true or yes, in any case. Most also accept on.
• Numbers that do not parse fall back to the default in almost every case.
• An empty line value such as OPENAI_API_KEY= sets nothing, so a stored secret can fill it, and hubzoid doctor warns about it.
• AWS Secrets Manager is optional. A secret named by AWS_SECRET_NAME, HUBZOID_HUB_SECRET_NAME or HUBZOID_RESTRICTED_SECRET_NAME is read at start and wins over the file of its layer. See configuration secrets.
• With several Hubs, each bridge loads its own Hub's .env, and a Hub's .env stays with that Hub. Settings for the whole deployment belong in hubzoid.yaml and in the .env next to it: the deployment key (HUBZOID_SECRET_KEY), DATABASE_URL, sign-in providers, ENABLE_SIGNUP and mail. That .env wins over the process environment. HUBZOID_PUBLIC_URL, HUBZOID_AUTH, HUBZOID_ADMIN_EMAIL and HUBZOID_IN_APP_EDITING fill a key hubzoid.yaml leaves out. A Hub .env that sets a different HUBZOID_AUTH or HUBZOID_SECRET_KEY stops the start with an error. Sign-in settings (OAUTH_*, OPENID_*, GOOGLE_CLIENT_*, MICROSOFT_CLIENT_*, ENABLE_SIGNUP, ENABLE_LOGIN_FORM, ENABLE_OAUTH_SIGNUP and HUBZOID_PUBLIC_URL) are still taken from the Hubs' .env files when the deployment's own settings lack them, and the start lists them.

hubzoid init writes a starter .env with a random bridge key and commented examples for each provider. hubzoid doctor checks the result and lists each key's layer by name. See doctor.

Models and reasoningCopy Anchor Link

A scheduled task's model: frontmatter and hubzoid schedule run --model override the model for that run only. See agents and models.

Credential failover keeps the same model and tools on every attempt. A request switches credentials only before any content or tool activity has started, and tries at most three. A limited credential waits for its reported reset, or five minutes without one, and a rejected login stays off until its token is replaced. Hubs that share an operational database share these cooldowns. Several tokens may draw on the same quota, so backups do not guarantee availability, and switching on a real exhausted subscription has not been induced in release testing. Restart the bridges after changing a token. See Claude credential failover (opens in a new tab).

Web app and sign-inCopy Anchor Link

These settings describe the chat UI and how people sign in. With several Hubs, set them once for the deployment, as described in how settings load.

Sign-in providersCopy Anchor Link

See authentication for setting up sign-in and the first administrator.

Server, ports and linksCopy Anchor Link

hubzoid run opens the web app in a browser only from a terminal on a loopback host, and on Linux only in a graphical session (DISPLAY or WAYLAND_DISPLAY). The standard BROWSER variable picks the browser. --no-open skips it.

Artifacts and emailCopy Anchor Link

These settings govern published artifacts, created with hub.publish_artifact or the markdown task tool publish_artifact, and workflow email, sent with hub.send_email or send_email. See the workflow API.

Email goes to the account the run acts as, or, from a team run, to the addresses of an email list declared in workflows/settings.yaml. Code and models cannot name any other recipient. A local or example account such as admin@localhost cannot receive email, so run the workflow as a real account or use preview. SMTP delivery over TLS is tested against stand-ins in release testing, not end to end against a real mail server. With several Hubs, these settings can be set once for the deployment, in the .env next to hubzoid.yaml, and overridden per Hub.

Databases and deployment stateCopy Anchor Link

The operational store resolves in this order: the registered deployment manifest, then HUBZOID_OPERATIONAL_DB, then DATABASE_URL, then the Hub's own database. The workflow engine resolves as: the manifest entry for the Hub, then HUBZOID_DBOS_DB, then DATABASE_URL when it is not SQLite, then <hub>/.hubzoid/dbos.db. When a manifest exists, a different HUBZOID_OPERATIONAL_DB or HUBZOID_DBOS_DB stops startup with an error instead of splitting the data. Change the deployment's configuration, not a single bridge.

BackupsCopy Anchor Link

See backup and restore.

Chat surfacesCopy Anchor Link

SlackCopy Anchor Link

WhatsApp and TelegramCopy Anchor Link

Generic webhookCopy Anchor Link

Webhooks that start code workflows are declared in workflows/settings.yaml and take their secrets from WEBHOOK_SECRET_<NAME>, listed under schedules and workflows. See WhatsApp and Telegram, Slack and webhooks.

Access and identityCopy Anchor Link

See identity and access and built-in tools.

Schedules and workflowsCopy Anchor Link

Personal schedules and Run for me runs act as the person who saved or started them, never as HUBZOID_WORKFLOW_USER. Other workflow limits, such as max_concurrent_workflows, agent_max_attempts, webhook declarations, email lists and alert rules, live in workflows/settings.yaml rather than the environment. See the workflow API and workflows and schedules.

A Hub's own workflow code can read more variables. A ready-to-use Hub lists them in its README and, when it declares them, in its settings.yaml, which hubzoid hub settings shows.

MCP and connectorsCopy Anchor Link

Connectors themselves are files, not environment variables: connectors/.mcp.json for servers everyone shares, and connectors/<id>.yaml for remote servers people sign in to (see Hub files). Settings can save them only when browser editing is on. See add a connector and connect an assistant.

Tools and the shared browserCopy Anchor Link

See tools and connectors and built-in tools.

TelemetryCopy Anchor Link

See observability.

Several HubsCopy Anchor Link

Sign-in and the deployment key are set once for the deployment, as described in how settings load. See several Hubs.

Remote CLICopy Anchor Link

Docker ComposeCopy Anchor Link

docker/docker-compose.yml in the SDK repository reads these from your shell.

HUB_PATH=$PWD/my-hub docker compose -f docker/docker-compose.yml up -d

See Docker.

Configuration secretsCopy Anchor Link

Each configuration layer can also read an AWS Secrets Manager secret that holds a flat JSON object of settings. Nothing here is needed when you use files alone. With no secret named, Hubzoid makes no AWS call. This path is tested against stand-ins in release testing, not end to end against AWS itself.

• Secrets are read at start with boto3's normal credential chain: an instance or task role, AWS_PROFILE, or access keys in the environment.
• Within a layer the secret wins over the file. A single Hub applies its deployment secret after its .env. A Hub that runs with others takes only the bridge's share of the deployment secret, before its own .env. That share covers workflow identity, email, report link settings, database URLs, the public address, HUBZOID_SECRET_KEY and telemetry.
• A secret may not set AWS_* keys, secret names or process control keys such as PATH, LD_* or PYTHONPATH. Values are strings, numbers or booleans.
• A secret that cannot be read stops the process at start with the secret name, the layer and the AWS error class, never a value.
• Values are read once. After a rotation, restart what reads the secret: the whole hubzoid run for the deployment secret, and the Hub, with hubzoid restart <hub>, for a Hub or restricted secret.
• hubzoid doctor reports each configured key's layer by name only, and whether each secret can be read. --skip-secret-fetch lists the secrets without calling AWS. See doctor.

No longer readCopy Anchor Link

MCP_ACCESS_GROUP has no effect. Access to MCP is a Use this agent grant in Settings, and personal MCP connections are connectors added in Settings. hubzoid doctor warns about a leftover MCP_ACCESS_GROUP. Remove it from older .env files.

Set by HubzoidCopy Anchor Link

Hubzoid sets these for its own child processes. You do not set them by hand.

Next stepsCopy Anchor Link