Access administration
Decide who may use each agent and its controlled tools, add and offboard people in Settings, and repair access from the server when you need to.
Hubzoid decides who may use each agent and which controlled tools they may call, with one access model managed in Settings however a Hub was created or deployed. Day to day, administrators work in Settings. The hubzoid admin, grant, revoke and access commands cover what has to happen on the server: the first administrator, scripted grants and recovery.
When to use this
Use this page when you set up a new deployment, add people or offboard them, or need to inspect or repair access from a shell. Sign-in itself is on authentication. The model behind access (identities, surfaces and the tool check) is on identity and access, and the screens are on agents and access.
Give someone access
- Open Settings → Agents, the agent, then Access.
- For someone new, choose Add user. Enter their name and email, choose what they may do starting with Use this agent, review, then Create account.
- Copy the one-time sign-in link Hubzoid shows once, and share it yourself. Nothing is emailed.
- For someone who already has an account, choose Edit access on their row, or open them under People and use Add an agent.
- Check with their account that the agent appears and a tool they were not given stays unavailable.
Changes take effect at the next permission check, in every bridge of the deployment. A person with no agent yet sees a notice in the chat instead of an empty agent list.
One access model
- A person may use an agent, or one of its controlled tools, only with a grant. Nothing else grants access. The groups in a Hub's
identity/access.csvroster grant nothing, though a roster still says who a WhatsApp or Telegram sender is.
New Hubs, the owner's first grants and refused calls
- A Hub deployed from git with no
.hubzoid/folder is managed like any other. Nobody can use it until someone is granted access. - The configured owner gets the owner's grants once, at their first verified sign-in as an administrator. With sign-in off, the local owner
admin@localhostowns every Hub from the first start. An API key never provisions anyone. - A call to a bridge without a verified person is refused.
hubzoid doctorwarns about an agent nobody may use, and notes one only its owner may use (access.who).
Grants
A grant is one row in the deployment's operational store: a subject, a Hub and a permission.
The parts of a grant
| Part | Values |
|---|---|
| Subject | A person's sign-in email. Older deployments can also hold legacy workflow identities (workflow:<name>, workflow:md:<task>) and a carried-over * for everyone signed in. |
| Hub | The Hub's folder name, which is its access domain, or the organization domain for organization administrators (--org) |
| Permission | use_hub (Use this agent), manage_access (Manage access), a built-in capability, a connector's connector_<id>, or the name of a restricted tool file, such as ledger for restricted/ledger.py |
Built-in capabilities come with Hubzoid and are off until granted.
Every built-in capability
| Capability | What it allows |
|---|---|
Save shared knowledge (curator) | Use remember to create or replace documents under knowledge/_learned/, when changing agent files from the browser is turned on |
Call Jev (jev) | Use the call_jev chat tool, billed to the Hub's JEV_OPENROUTER_API_KEY |
Share artifacts publicly (share_public_links, sensitive) | Create links anyone who has them can open without signing in |
Share reports with the company domain (share_domain_links, sensitive) | Give a report a link anyone at the company's share domains can open after signing in |
See workflows and runs (workflows_view) | List this agent's workflows and recent runs from chat or an assistant |
Run and control workflows (workflows_manage, sensitive) | Start, pause, resume and cancel this agent's workflows from chat or an assistant |
Schedule reports for themselves (schedule_reports) | Save personal schedules of the reports they can run |
Run report (wf_<workflow>) | Run one workflow offered in chat, as themselves |
Manage access from chat (access_tools, sensitive) | Use the access tools in this agent's chat. Only organization administrators grant it. |
Rules the store enforces on every write
The store enforces these rules on every write:
- Granting any tool permission also grants
use_hubin the same Hub, so a grantee can always open the agent. - Revoking
use_hubremoves every permission that subject holds in that Hub. - The organization domain accepts only
manage_access. - New grants to
*(everyone signed in) are refused everywhere. - The last organization administrator cannot be revoked, demoted or deleted.
use_hub and manage_access are reserved names, and connector_ is a reserved prefix. Every other permission comes from a file in the Hub's restricted/ folder. Optional labels, descriptions and a sensitivity flag come from identity/permissions.yaml, which cannot relabel a built-in:
ledger:
label: Read ledger
description: Read accounting entries for this agent.
sensitive: trueSensitivity is only what this file says. Hubzoid never infers it from a name.
Administrators
A person with manage_access in one Hub is an agent administrator for that Hub, and can also open and chat with it.
What an agent administrator can and cannot do
In each agent they manage, they grant or remove only capabilities they hold there themselves, never manage_access, and cannot change their own access or an organization administrator's. They can create a normal account with access in their agents, but cannot approve, reset passwords, change roles or delete accounts.
A person with manage_access in the organization domain is an organization administrator for every Hub. That does not by itself grant chat or any tool, so an administrator still needs Use this agent to chat with an agent. Set someone's Role to Administrator under Settings → People, the person, or run hubzoid admin set-role <email> admin <hub> on the server.
How the Administrator role and Needs attention work
Administrator sets organization administration and the account's administrator role together. A person who is an administrator on only one side shows Needs attention, and choosing their role fixes it.
Administrators must set up two-step sign-in by default. The Two-step column under People shows who has, and Reset two-step sign-in on a person's page clears a lost authenticator. See authentication.
The first administrator
The configured owner is the first administrator: HUBZOID_ADMIN_EMAIL (or owner in hubzoid.yaml), else the owner the deployment recorded. On their first verified sign-in they receive organization administration and Use this agent in each Hub, once. A later sign-in never restores access you revoke. Authentication covers creating the account.
For a deployment nobody can administer, grant organization administration from the server. For several Hubs run together, start hubzoid run first so its Hubs are registered.
hubzoid access bootstrap --admin sam@example.com ./finance--admin can be repeated. Bootstrap grants administrators on its first successful run only, so it cannot be used to add administrators later.
Accounts in Settings
Accounts live in Hubzoid's operational store, and every action is recorded under Activity → Audit log.
| Action | Who | Where |
|---|---|---|
| Add user: a new account with its first access | Organization administrators, and agent administrators within their own access | An agent's Access tab, or People |
| Change an existing user's access | The same | Edit access on their row, or People, the user, Edit access or Add an agent |
| Approve a pending sign-up, reset a password or two-step sign-in, record a phone number | Organization administrators | People, the user |
| Set Role to User or Administrator | Organization administrators | People, the user |
| Delete user, or Reactivate a blocked user | Organization administrators | People, the user, the … menu |
Google-only accounts, existing emails and phone numbers
Google sign-in only in Add user creates the account with no password when Google sign-in and OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true are configured. An email that already has an account changes nothing, and Settings links to that user so you edit their access instead. A phone number recorded on a person is how their WhatsApp and Telegram messages are recognized.
Offboard someone
Use Delete user and type the person's email to confirm. It removes every grant and ends every credential: sessions, API keys and assistant connections.
What deletion keeps, and blocked accounts from older releases
Their share links stop working, and their chats stay attached to the removed account. Activity history, usage records and published artifacts are kept, and the email is marked as removed, so a later account with it inherits nothing. Only an organization administrator can create an account with that email again. Copies in your backups follow your own retention policy.
Settings does not offer Block. A person blocked by an older release shows as Blocked, and new access for them is refused. An organization administrator chooses Reactivate from the … menu, or deletes them. Reactivating does not restore the grants the block removed.
Everyone signed in
Nobody can create access for everyone signed in. An agent that had it before keeps an Everyone signed in row on its Access tab, which keeps working until an organization administrator selects Remove on it. Give the people who need the agent named access first. From a shell: hubzoid revoke '*' use_hub --hub <hub> <hub_dir>.
Workflow identities
Scheduled workflows and markdown tasks run as an ordinary account: run_as on the declaration or in the task's frontmatter, else HUBZOID_WORKFLOW_USER (the Hub's, then the deployment's), else the owner recorded at setup. Grant that account the permissions the work needs, like any person. For shared automation, create an ordinary account such as reports@example.com.
Account requirements, and moving from legacy workflow subjects
The account must have signed in once, must not be waiting for approval or blocked, and must hold Use this agent. Otherwise the run fails with the fix in its error, and Hubzoid never falls back to another account. hubzoid schedule list <hub> and Runs as on the agent's Workflows tab show who each one runs as.
Grants to the older workflow:<name> and workflow:md:<task> subjects are kept, but runs do not use them. When a run's account lacks a permission the old subject held, the run log names it. Settings lists these subjects as Legacy service identity and cannot add new ones. To move over, grant the account and then remove the old grant:
hubzoid grant reports@example.com ledger ./finance
hubzoid revoke workflow:month_end_close ledger ./financeAccess and workflows from chat
Two families of agent tools are off for everyone until granted, under Hubzoid tools in the access editor:
- Manage access from chat (
access_tools). A manager can ask the agent who has access to an agent they manage, why a person has it, and propose an access change or a new account. The agent replies with a link to Settings, where the same manager reviews and confirms the exact change. Nothing applies before that. - See workflows and runs and Run and control workflows (
workflows_view,workflows_manage). They act only on the agent they run in.
Proposal expiry, runs started from chat, and turning the tools off
A proposal works once and expires after HUBZOID_CHANGE_REQUEST_TTL seconds (default 900). The access tools refuse anonymous callers, scheduled workflows and every Slack surface.
A run started from chat acts as the workflow's own account and is recorded with the person who started it.
HUBZOID_ACCESS_TOOLS=false or HUBZOID_WORKFLOW_TOOLS=false in a Hub's .env removes a family from that agent. The older HUBZOID_MANAGEMENT_TOOLS=true still gives every manager the access tools without a grant, and hubzoid doctor warns about it. Grant access_tools to the managers who use them, then remove the setting.
Command reference
Every command takes the Hub directory as its last argument (default: the current directory) and finds the operational store through the Hub, including the shared store of several Hubs run together.
| Command | What it does |
|---|---|
hubzoid grant SUBJECT PERMISSION [HUB_DIR] | Grant one permission. --hub NAME targets another Hub's domain, --org the organization domain. |
hubzoid revoke SUBJECT PERMISSION [HUB_DIR] | Revoke one permission. Same --hub and --org options. |
hubzoid access check SUBJECT [HUB_DIR] | Every permission the subject effectively holds in the Hub. --hub NAME, --json. |
hubzoid access list [HUB_DIR] | Every grant as subject, permission and Hub. --hub NAME limits it to one Hub, --json. |
hubzoid access bootstrap --admin EMAIL [HUB_DIR] | Organization administrators for a deployment nobody can administer, on the first successful run only |
hubzoid admin ... | Accounts: create, reset passwords, list and set roles. See the admin command. |
hubzoid audit [HUB_DIR] | Recent tool decisions. See observability. |
hubzoid grant priya@example.com ledger ./finance # also grants use_hub
hubzoid access check priya@example.com ./finance
hubzoid revoke priya@example.com use_hub ./finance # removes all of Priya's finance permissionshubzoid grant also accepts an email that has no account yet. The access applies when someone first signs in with that email, for example through single sign-on.
Upgrading from older releases
Older releases had a second, group-based access mode. It is gone, and so are hubzoid access migrate, rollback and diff, access bootstrap --authoritative and the .hubzoid/fresh-install marker.
What the upgrade changed, and what to check after
An upgrade gave each group member the grants and shares their groups held. MCP_ACCESS_GROUP is no longer read, and hubzoid doctor warns while it is present (mcp.access_group). After upgrading, run hubzoid doctor on each Hub and grant Use this agent wherever access.who reports that nobody may use an agent.
If something goes wrong
| What you see | What to do |
|---|---|
| A grant has no effect | The command used the wrong Hub directory, the grant's email differs from the sign-in email, or the person is blocked. |
| Nobody may use an agent | hubzoid doctor reports access.who. Grant Use this agent in Settings, or sign in once as the configured owner. |
| Settings shows only the personal sections | The account lacks manage_access. An organization administrator sets their Role to Administrator, or grants Manage access in one agent. |
| Someone keeps access after a revoke | The agent still has a carried-over Everyone signed in row. Remove it, or offboard with Delete user. |
| A workflow run fails with no account to run as | Set run_as or HUBZOID_WORKFLOW_USER, and check that the account has signed in once and holds Use this agent. |
More problems and fixes
| What you see | What to do |
|---|---|
hubzoid grant '*' ... is refused | New access for everyone signed in cannot be created. Grant named people. |
| A person shows Needs attention | They are an administrator on only one side. Choose their Role under People. |