Console overview

The Console is where administrators add users, decide who can use each agent, inspect workflow runs and review what happened. The Hubzoid bridge serves it at /portal/. Access, runs and activity come from Hubzoid's own records: the access store, the decision log, usage rows and the workflow engine's run history. Accounts and sign-in stay in the chat app. When you add, approve or delete a user, the Console makes that change through the chat app's admin API, as the deployment's service account.

When to use thisCopy Anchor Link

Open the Console to add a user, grant or remove access to an agent, approve a sign-up, check scheduled work after a deploy, find out why a tool call was refused, or see how much each agent is used. Server-side operations, such as starting, pausing or cancelling runs and migrating hubs, stay in the CLI.

Where it livesCopy Anchor Link

The edge routes /portal to the bridge on the chat app's public port, while the bridge's /v1 API stays private. In the chat app, anyone allowed into the Console sees Admin Console above their profile in the sidebar. When the sidebar is collapsed it shows as an icon with a tooltip. The link appears only while the signed-in account passes the Console's check.

Every screen has a bookmarkable address after the #, such as #/agents/finance/access or #/people. Filters and page numbers are part of the address as well, so a filtered view can be shared and survives a refresh or the Back button.

Who can open itCopy Anchor Link

The Console has no login of its own. It reuses the chat app's session: the session cookie is checked on the server against the chat app (GET /api/v1/auths/), and the verified email is what counts. Identity headers sent by a browser are ignored. An account that is still awaiting approval in the chat app is refused. Sign out in the Console signs out of the chat app.

The verified email must then hold manage_access:

Anyone else sees "Console access is not enabled for this account", with a button back to the chat app. The chat app's admin role alone does not open the Console. Every change sent from a browser session must come from the Console's own origin. A request whose Origin or Referer does not match the host is refused.

The first administratorCopy Anchor Link

The deployment's configured owner becomes the first administrator the first time they sign in:

• Locally, with sign-in off, the owner is the chat app's single admin@localhost account, so the Console opens straight away at /portal/.
• On a server, the owner is the chat app administrator whose email matches HUBZOID_GATEWAY_ADMIN_EMAIL, or WEBUI_ADMIN_EMAIL when that is not set. Set it before the first sign-in.

At that sign-in Hubzoid grants the owner organization administration, unless administrators were already set up with hubzoid access bootstrap, and Use this agent in each hub. Hubs created fresh with hubzoid init switch to managed access. Existing hubs keep their access mode until you migrate them. This happens once: a later sign-in never restores access that was removed, and no other chat app administrator or user is promoted.

For headless setups and recovery, bootstrap on the server instead:

hubzoid access bootstrap --admin you@example.org --authoritative ./finance

• --admin grants manage_access in * only while no administrator has been set up yet, by an earlier bootstrap or by the owner's first sign-in. Later runs add no administrators, but they still mark further hubs as managed with --authoritative.
• --authoritative makes the hub managed, so its access is edited in the Console. Bootstrap refuses this when no organization administrator exists, because nobody could open the Console afterwards.
• Add more administrators under People: open the user and set Role to Administrator, which makes them an administrator in the Console and in the chat app together. On the server, hubzoid grant colleague@example.org manage_access --org ./finance sets only the Hubzoid side, so the Console marks that user Needs attention until you choose a role.
• For a gateway with several hubs, and for hubs that still use chat app groups, follow Access administration.

NavigationCopy Anchor Link

Runs and schedules live inside each agent. The old cross-agent runs list has no sidebar entry, but #/runs still opens it, so earlier links keep working. #/confirm/<id> is the page where you confirm a change that an agent proposed for you, when a hub sets HUBZOID_MANAGEMENT_TOOLS=true. It shows the exact change with Apply change (or Create account) and Reject. Only the person who asked can open it, it works once, and it expires after HUBZOID_CHANGE_REQUEST_TTL seconds (900 by default).

The sidebar footer holds a theme switch (light, dark or match the system), Open chat, your email with your role (Administrator or Agent administrator), and Sign out. On a phone the sidebar moves into a menu opened from the top bar.

The Agents pageCopy Anchor Link

The Console opens on Agents. Choose 24 hours, 7 days or 30 days at the top of the page. The default is 7 days. Refresh reloads the totals, the agents and their workflow status, and the time of the last update shows beside it. Agent administrators see only their agents.

TotalsCopy Anchor Link

Five cards sit above the agents:

The info buttons next to Users, Tokens used and Approx. cost explain each figure.

Agent cardsCopy Anchor Link

Each card shows the agent's name and key, its access and workflow tags, Tokens used and Approx. cost for the chosen period, and the buttons Manage access, Runs & schedules and Activity. Search with Find an agent. The tags and each agent's page are described in Agents and access.

Unknown is never zeroCopy Anchor Link

A figure Hubzoid cannot know is shown as a dash, never as zero. If the chat app's account directory cannot be read, Users reads Unavailable. If the run history cannot be read, Workflow runs reads Unavailable. If no price is known for the model calls, the cost is a dash. A cost that leaves out some calls with no known price is marked with *, and its tooltip says how many. A very small cost shows as < $0.01. If a refresh fails, the page keeps the last numbers and says it could not refresh them.

Usage comes from Hubzoid's own hz_usage table, which records every chat turn and workflow model call without message content. Runs come from the workflow engine's run history. Only Users reads the chat app, from its account directory. The usage numbers are therefore the same whichever chat front end serves the agents.

The API behind the ConsoleCopy Anchor Link

The Console is a static app over a JSON API under /portal/api, protected by the same session check. The same API is the management API for scripts: every endpoint also accepts Authorization: Bearer sk-... with an Open WebUI API key, and the caller acts as the key's owner under the same rules. A key caller needs no Origin header. A refusal returns a JSON body with detail, which is safe to show, and a stable code, such as outside_ceiling or last_admin.

The full list of Hubzoid endpoints is in HTTP endpoints.

Next stepsCopy Anchor Link

Read this page as Markdown