Quickstart

Create a HubCopy Anchor Link

hubzoid init my-hub

hubzoid init creates my-hub/ under the current folder from a bundled template and writes three things:

• The Hub files: AGENTS.md plus one worked example in agents/, skills/, knowledge/, tools_local/, connectors/, schedule/, evals/, raw_data/ and branding/.
• A .env file with MODEL=claude-local, commented stanzas for OpenRouter, OpenAI and Anthropic, and a random BRIDGE_API_KEYS value. The file is created with mode 0600 because it holds a live key.
• When the parent folder is empty or holds only a README, requirements.txt, a license file or dotfiles, a small agents repository wrapper: requirements.txt pinned to your installed Hubzoid version, .gitignore and README.md. Run hubzoid init again in the same folder to add more Hubs beside the first one. Parent files are written only once.

Without --force, existing files are skipped and the command reports how many.

Choose a modelCopy Anchor Link

The model is set by MODEL in my-hub/.env. The default, claude-local, needs no API key: Hubzoid runs the Claude Agent SDK against your installed claude CLI, and a logged-in CLI draws on your Claude Pro or Max subscription.

MODEL=claude-local              # Sonnet
# MODEL=claude-local/opus       # Opus
# MODEL=claude-local/haiku      # Haiku, lower latency

claude-local authenticates in one of three ways:

If the Codex CLI is signed in instead, use codex-local, which runs the Hub on local Codex. It needs Codex CLI 0.147.0, signed in with file-backed credentials (codex -c 'cli_auth_credentials_store="file"' login) as the account that runs Hubzoid, on macOS or Linux. In an interactive terminal, hubzoid init picks whichever CLI is signed in and asks once when both are.

MODEL=codex-local
# MODEL=codex-local/<model-id>  # optional model pin

To use a hosted provider instead, comment out the local model, set MODEL to a LiteLLM model id and add the matching key:

# MODEL=claude-local
OPENROUTER_API_KEY=sk-or-v1-...
MODEL=openrouter/anthropic/claude-haiku-4.5

MODEL in .env wins over a model: line in AGENTS.md. With neither set, the Hub uses claude-local. If the key for the chosen provider is missing, the agent does not build and the error names the variable to add. Agents and models covers per-agent models and runtime settings.

Run the HubCopy Anchor Link

hubzoid run my-hub

hubzoid run starts three processes: the bridge on 127.0.0.1:8000, the Open WebUI chat app on a loopback port, and the edge router on port 3080, which is the one address you open. When the webui line in the terminal says ready, open http://localhost:3080.

Stop everything with Ctrl+C. Most changes to Hub files take effect the next time you start it. Knowledge files are read live, each time the agent calls read_knowledge.

Have your first conversationCopy Anchor Link

The chat opens without a sign-in page, because sign-in is off by default for local use. The model picker shows your Hub's agent, and the empty chat offers the prompts from the suggestions: list in AGENTS.md:

• What is in this hub?
• Greet me with the hello skill
• List my skills and knowledge

The hello prompt shows the full path through a Hub: the agent loads the hello skill from skills/hello.md, which tells it to call the hello tool defined in tools_local/hello.py. Each tool call appears in the answer as a collapsible entry.

You can send a prompt from the terminal too. hubzoid test builds the agent in-process, without the bridge or the chat app:

hubzoid test my-hub --prompt "What is in this hub?"

Now make the Hub yours. Replace the body of my-hub/AGENTS.md with the agent's real job, put reference material in knowledge/, and restart hubzoid run.

Check the HubCopy Anchor Link

hubzoid doctor my-hub

On a fresh local Hub, expect passing checks for the files, the agent build and the bridge key, an information line saying chat sign-in is off (fine for local use only), and a warning that no backup has been recorded yet. Fix anything marked as failed. The command exits with code 1 while any check fails. See the doctor reference.

Open the ConsoleCopy Anchor Link

The Console is served on the same port, at http://localhost:3080/portal/. With sign-in off, the chat app has one account, admin@localhost, and Hubzoid makes it the Hub's owner the first time you open the chat or the Console: an administrator in the Console with Use this agent in the Hub. A Hub created with hubzoid init uses managed access from the start, so there is nothing to set up. Open /portal/ directly, or select Admin Console above your profile in the chat sidebar. There is no second password.

The Console opens on Agents: usage totals for the chosen period above one card per agent. Each agent holds its access, its runs and schedules, and its activity. People lists accounts with their role and access, and Activity shows access changes and tool decisions. A new Hub starts with empty usage and run history, so send a chat first. The Console overview explains each screen.

Teammates need their own accounts, which means turning sign-in on and giving the Console the chat app's service account in HUBZOID_GATEWAY_ADMIN_EMAIL and HUBZOID_GATEWAY_ADMIN_PASSWORD. You then add them with Add user and share their sign-in details yourself. Authentication covers the sign-in options, and access administration explains how Hubzoid manages who can use each agent.