Quickstart
Create a Hub, run it on your laptop and get your first answer from your own AI agent in about five minutes. Open source, in Python, on your own machine.
You will create a small Hub, start the Hubzoid web app and ask the agent a question it answers from a file you can edit. Then you will check it, look around Settings and connect Claude Code.
What you need
- Hubzoid installed in a Python 3.11 or 3.12 virtual environment. See installation.
- A model. The simplest is a signed-in Claude Code (opens in a new tab) CLI on this machine, which needs no API key. A Codex CLI login or an OpenRouter, Anthropic or OpenAI key also work.
Create a Hub
hubzoid init my-hubThis creates my-hub/, a small starter for Kestrel & Oak, a fictional home-goods shop. It has every folder Hubzoid reads, three house rules in knowledge/house-rules.md, one check in evals/ and a private .env file.
Initialized hub at ~/agents/my-hub
wrote 7 hub files
Next:
1. Check the model in ~/agents/my-hub/.env: MODEL=claude-local uses a signed-in `claude` CLI.
2. hubzoid run ~/agents/my-hub (opens the web app in your browser)
3. Ask: "A customer wants a refund 40 days after delivery. What can we offer?"Check the model
Open my-hub/.env. The default needs no key when the claude CLI is signed in on this machine:
MODEL=claude-localNo Claude Code? Pick one of these instead and save the key in the same file:
MODEL=codex-localNeeds Codex CLI 0.163.0 or 0.147.0, signed in with file-backed credentials. See agents and models.
Start the Hub
hubzoid run my-hubWhen everything is up, Hubzoid prints one ready line and opens the web app in your browser:
✓ Hubzoid is ready: http://127.0.0.1:3080 (local mode, sign-in off)
Connect Claude Code: claude mcp add --transport http my-hub http://127.0.0.1:3080/mcpSign-in is off on your laptop, so there is no sign-in page. You are the Hub's owner. Stop it any time with Ctrl+C.
Ask your first question
Choose the first suggestion, or type it:
A customer wants a refund 40 days after delivery. What can we offer?The agent reads the house rules and answers from them, naming the file it used:
Now make it yours. Change both 30s in my-hub/knowledge/house-rules.md to 45, restart hubzoid run and ask again. This time the agent offers a full refund, because 40 days is inside your new window. A correction typed only in chat is not saved as shared knowledge.
Check it works
The starter comes with one check. Run it:
hubzoid eval run my-hub1 case(s) · my-hub
✓ refund-window
case judge time reason
refund-window PASS 10/10 5.3s
1 passed of 1hubzoid doctor my-hub checks the whole setup and explains anything that needs attention. See evals and the doctor reference.
Look around Settings
Open Settings from the account menu, or go to http://127.0.0.1:3080/settings. Agents lists your Hub. Open it to see its instructions, who can use it, its workflows and its eval results.
Connect Claude Code
Use the same Hub from Claude Code. Paste the line hubzoid run printed:
claude mcp add --transport http my-hub http://127.0.0.1:3080/mcpIn Claude Code, run /mcp, choose my-hub and authenticate. Your browser opens Hubzoid's consent page. Choose Allow connection. Claude Code can then read the Hub's knowledge and use its tools with your access. See connect an assistant.
If something goes wrong
| What you see | What to do |
|---|---|
hubzoid: command not found | Activate the virtual environment you installed Hubzoid into. |
| The agent does not build and names a variable | The model key is missing. Add that variable to my-hub/.env. |
claude-local answers with a sign-in error | Run claude once and sign in, or choose another model in step 2. |
| The browser did not open | Open http://127.0.0.1:3080 yourself. |
| Port 3080 is in use | Start with hubzoid run my-hub --port 3090. |
Let Claude Code or Codex set it up
Paste this into Claude Code or Codex from an empty project folder. Replace the text in angle brackets with the job you want the agent to do.
Set up a local Hubzoid Hub in this folder.
1. Create a Python 3.11 or 3.12 virtual environment and run: pip install hubzoid
2. Run: hubzoid init my-hub
3. Pick the model in my-hub/.env. Keep MODEL=claude-local if the `claude` CLI
is signed in. Otherwise ask me which provider to use, then set MODEL and its
key in my-hub/.env. Never paste a key into chat.
4. Run: hubzoid doctor my-hub and fix every failed check.
5. Run: hubzoid eval run my-hub
6. Rewrite my-hub/AGENTS.md for this job: <describe the job in one paragraph>.
Put my material in my-hub/knowledge/<topic>.md. Show me the changes first.
7. Start it with: hubzoid run my-hub, ask it my real task and show me the answer.
Keep secrets only in my-hub/.env. Do not commit .env or .hubzoid/.In Claude Code you can install the Hubzoid plugin instead. Then ask it to set up a Hubzoid Hub for your work, or run /hubzoid:build-hub.
/plugin install hubzoid --marketplace hubzoid/hubzoidIn Codex, add the same plugin from your shell:
codex plugin marketplace add hubzoid/hubzoid
codex plugin add hubzoid@hubzoid