Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Instance access role member (owner minus member management)
Superseded Member operation scope (2026-09-17): Instance Member operations is authoritative for Member resource use and runtime visibility on both instance kinds. Member is a current-instance operator; the older Organization Agent/Project/session ACL restrictions below are historical and no longer apply to Member. Editor/Viewer, true Owner identity, access-administration and ownership safeguards remain. Existing Show publication policy and shared inbox read-state semantics remain unchanged. Shipped pre-catalog Member selection/session fallbacks are retained; new Task/Watch binding names still require catalog entries.
Issue: https://github.com/avibe-bot/avibe/issues/1596 Related: https://github.com/avibe-bot/avibe/pull/1562 (Personal editor resource-ACL semantics — the capability model this role plugs into)
This file is the cross-lane contract. Field names, role identifiers, and capability names are exact. Deviations require orchestrator sign-off.
Decisions (frozen)
- Identifier: the instance access role string is
member(notadmin, notinstance_member). - UI / docs copy: display the instance access role as "Member" (ZH: 「管理者」). The stored/token value remains
member. (Superseded 2026-09-18: the Chinese label was 「成员」 when this was frozen, accepting the overlap with the cloud organization-role copy. The owner replaced it with 「管理者」 to end that overlap; English is unchanged. Authoritative record:docs/plans/editor-permission-parity.md.) - Ownership transfer stays owner-only.
membercannot transfer instance ownership (Personal or Organization). Treat it as member management. - Applies to both Personal and Organization Avibe.
- Personal vs Organization ACL:
memberis treated as editor-or-higher for the Personal resource-use bypass (has_role("editor")already covers it once rank isviewer < editor < member < owner). Organization ACL evaluation is unchanged for use:memberis still subject to Agent / Project resource ACL like any non-owner Organization principal. Agent management is owner-equivalent at the resource layer, including resources owned by another subject, resources bound to another organization policy, and resources with no policy row.
Role axis (instance access)
viewer < editor < member < owner
Stored / token / session payload value: vibe_instance_role ∈ {owner, member, editor, viewer}.
Allowlist entry role (cannot be owner; owner is implicit via instance.ownerUserId):
InstanceAccessEntryRole = "member" | "editor" | "viewer"
Project access bindings stay {editor, viewer} — do not add member to project ACL rows. A member instance role on a restricted Organization project is narrowed by the existing min(instance_role, binding_role) rule (so a member bound as viewer becomes viewer).
Organization roles stay {owner, admin, member} and are a separate axis. Never conflate them.
Capability contract
Exact capability names. Source of truth: AuthorizationContext in vibe/authorization.py.
| Capability | viewer | editor | member | owner |
|---|---|---|---|---|
can_read_instance |
yes | yes | yes | yes |
can_chat |
no | yes | yes | yes |
can_use_cloud_asr |
no | yes | yes | yes |
can_use_resource("agent"|"skill"|"vault_secret") |
no | yes | yes | yes |
can_use_resource("show_page") |
yes | yes | yes | yes |
can_use_terminal / can_use_files / can_use_terminal_files |
no | yes | yes | yes |
can_manage_projects |
no | no | yes | yes |
can_manage_agents |
no | no | yes | yes |
can_manage_instance |
no | no | yes | yes |
can_use_system |
no | no | yes | yes |
can_manage_access_members (NEW) |
no | no | no | yes |
is_instance_owner |
no | no | no | yes |
is_instance_owner remains instance_role == "owner" (identity, not rank). Canonical-owner control-plane actions (pairing keys, hostname writes, ownership transfer, allowlist mutate) stay canonicalOwnerRequired.
capability_projection() MUST include the new key:
"can_manage_access_members": <bool>
Existing keys keep their names and types. Frontend InstanceCapabilities adds the same key.
Rank
_ROLE_RANK = {"viewer": 1, "editor": 2, "member": 3, "owner": 4}
INSTANCE_ROLES = frozenset({"owner", "member", "editor", "viewer"})
has_role("owner") is true only for owner. has_role("member") is true for member and owner. has_role("editor") is true for editor, member, and owner.
Therefore:
can_manage_projects/can_manage_agents/can_manage_instance/can_use_systemchange fromhas_role("owner")tohas_role("member").can_manage_access_membersishas_role("owner")(equivalentlyis_instance_owner).
Member-management surface (owner-only)
These MUST require can_manage_access_members (not the broader can_manage_instance):
App (avibe):
PUT /api/permissions/authorized-users(vibe/ui_server.pycurrent-instance authorized-users PUT)- Any other handler that adds / removes allowlist entries or changes an access role
- Ownership-transfer UI / API, if any local surface exists (keep owner-only)
Backend (avibe-backend):
instance.authorized_users.mutate(allowlist add/remove/replace) — remainscanonicalOwnerRequired- Instance ownership transfer — remains
canonicalOwnerRequired - Pairing-key issue/rotate, custom hostname writes — unchanged, still canonical owner
member MUST be a valid value of an allowlist entry (so an owner can grant member), but a principal whose own role is member cannot mutate the allowlist.
Token / session payload contract (cross-repo)
Produced by avibe-backend (lib/security.ts cloud token vibe_instance_role; lib/oidc/authorization-context.ts; app/api/v1/instances/[instanceId]/user-token).
Consumed by avibe (vibe/authorization.py context_from_session_payload, vibe/remote_access.py _validated_authorization_payload).
| Field | Type | Semantics |
|---|---|---|
vibe_instance_role |
"owner" | "member" | "editor" | "viewer" |
Instance access role. Unknown values fail closed (empty context). |
vibe_instance_access_source |
existing enum, unchanged | |
vibe_instance_kind |
"personal" | "organization" |
server-owned; unchanged |
vibe_instance_id |
string | pairing identity; unchanged |
Allowlist schema:
remote_access_allowlist_entries.role: enum["viewer", "editor", "member"], default"viewer"- CHECK constraint updated to match
oauth_authorization_codes.instance_access_role: enum["owner", "editor", "viewer", "member"](nullable snapshot)InstanceAccessRoletype includes"member"InstanceAccessEntryRole = Exclude<InstanceAccessRole, "owner">therefore becomes"member" \| "editor" \| "viewer"automatically
Project ACL (access_role editor|viewer) is out of scope.
Persisted-shape rule
- Older releases never write
member. Loaders MUST keep accepting{owner, editor, viewer}snapshots with nomemberfield. - An unknown role value fails closed (empty / unauthorized context), never crashes startup.
- Backend migration: add
memberto the allowlist CHECK; existingviewer/editorrows unchanged. Provide a load fixture covering a pre-memberallowlist row. - App:
context_from_session_payloadacceptsmember; payloads without it behave as today. - Deferred
resource_user_contextsnapshots: avibe_instance_role: "member"written by this release must round-trip; a snapshot without the field keeps its previous role.
HTTP / SSE policy (app)
- Default
/api/minimum stays fail-closed. - Member-reachable management routes are explicitly declared in
_MEMBER_HTTP_RULES; unknown APIs remain Owner-only. Ordinary instance management includes Model Hub, backend/platform credentials, host lifecycle, safe remote transport settings and existing DM preferences. Access-member/role administration, pairing identity, Project/Resource ACL writes, WeChat QR binding and bulk ownership onboarding remain protected. Mixed settings writes preserve access effects at the locked writer; see Member management parity. POST /api/agents/defaultrequires the member tier and its setter requirescan_manage_agents. The default remains advisory: assigning a private or scope-policy Agent does not widen its ACL, and callers who cannot use it degrade to another usable Agent at resolution time.- Privileged SSE events (definitions/runs/vaults updated) currently require owner. Member receives them (they are instance-management events, not member-management). Implement by treating them as
has_role("member"). - Editor SSE (
queue.updated) and viewer SSE unchanged.
Frontend
ui/src/lib/sessionInfo.ts:instance_role: 'owner' | 'member' | 'editor' | 'viewer';InstanceCapabilities.can_manage_access_members: boolean.- Permissions page (
ui/src/features/permissions/): role picker offersmember; controls that mutate members / roles requirecan_manage_access_members(notcan_manage_instance). - i18n: EN
"Member"/ ZH"管理者"for the instance-access role (ZH superseded 2026-09-18; it read"成员"here, accepting the overlap with organization-member copy). - AppShell / Workbench / settings: continue to key off capabilities. After projection includes
can_manage_instance=truefor member, those surfaces light up automatically. Member-management widgets must additionally requirecan_manage_access_members.
Tests (property, not enumerations)
Seed one principal of every existing role plus member, run the change, assert:
membercan do every owner instance operation except member management and ownership transfer.membercannot add/remove allowlist entries or change roles (HTTP 403 / capability false).ownerstill can.editor/viewercapabilities unchanged vs current master.- Unknown role still fails closed.
- Pre-
memberallowlist / token / snapshot fixtures still load. - Personal
membergets the Personal editor resource-use bypass (Agent + projects); Personalviewerdoes not. - Organization
memberremains subject to Agent / Project ACL for use; Agent management is owner-equivalent at the resource layer. - Instance-access role copy is
"Member"/"管理者"(ZH superseded 2026-09-18, was"成员") without changing the stored value.
Lane split
Lane B — avibe-backend (codex)
Repo: avibe-backend, branch from latest origin/main.
Scope (no-touch for lane A):
lib/types.ts(InstanceAccessRole,InstanceAccessEntryRole)lib/oidc/authorization-context.tslib/db/schema.tsallowlist + oauth snapshot enums + CHECKs- new drizzle migration (allocate next revision against
origin/mainHEAD at rebase) lib/instances.tsresolveInstanceAccess(member is a valid allowlist role; editor-vs-viewer aggregation becomes editor-or-member-or-viewer with member > editor > viewer if any aggregation exists)lib/security.tstoken mintvibe_instance_roleapp/api/instances/[instanceId]/authorized-usersand v1 equivalent (acceptmemberas an entry role; mutate still canonical-owner)- store drizzle/memory allowlist writers
- tests covering schema, resolution, token projection, persisted pre-
memberfixtures - i18n / console labels if the org console exposes the allowlist role picker
Do not touch avibe-app files.
Lane A — avibe (claude)
Repo: avibe, branch from latest origin/master.
Scope (no-touch for lane B):
vibe/authorization.py(roles, rank, capabilities, HTTP/SSE policy, projection)core/vibe_agents.py(Agent management/default gates and pre-catalog entitlement fallbacks)vibe/ui_server.py(authorized-users PUT and any sibling member-mutation gate →can_manage_access_members)vibe/permissions.pyif it validates allowlist rolesvibe/remote_access.pyonly if it independently validates the role setstorage/project_access_service.py/storage/resource_access_service.pyonly if they hardcode{owner,editor,viewer}instead of usinghas_role/INSTANCE_ROLESui/src/lib/sessionInfo.ts,ui/src/features/permissions/*, i18n en/zh- focused tests: instance authorization, HTTP policy, permissions page / capability projection, persisted snapshot fixtures
ui/build if UI files change
Do not touch avibe-backend files. Consume the token field vibe_instance_role: "member" as documented; if backend is unmerged, tests stub that payload.
Merge / deploy order
Backend first (token + allowlist can already emit member; old app treats unknown-or-absent as fail-closed / ignore). App second (understands member, exposes the capability). Independent PRs, no stacked PR. App PR body declares "expects backend #NNNN merged first" once the backend PR exists.
Out of scope
- Changing organization roles
- Adding
memberto project ACL bindings - Billing / plan gates
- Renaming the organization role
member
Addendum: Agent management alignment (2026-08-21)
Divergence found
The initial implementation left three authorization layers inconsistent. The capability projection granted can_manage_agents to member, and the HTTP allowlist admitted Agent CRUD, but storage/resource_access_service.py::_policy_allows_management still required every non-owner to match the resource policy's owner_user_id. Built-in SYSTEM Agents such as claude and codex normally have no policy row, so the missing-policy fail-closed path denied every member mutation even though the capability and router both admitted it.
Owner decisions
membergets owner-equivalent Agent management at the resource layer. This includes built-in Agents, Agents owned by other subjects, missing-policy rows, and Organization policies bound to another organization. Editor behavior is unchanged. Resource use remains ACL-governed, and_policy_allows_owner_controlremains limited to the Instance Owner or resource owner.- Instance-wide default Agent selection is open to
member: the HTTP route is member-tier andset_default_agent_nameusescan_manage_agents. Bulk Agent onboarding and credential/host-lifecycle routes remain Owner-only. - The instance-access role display copy is
"Member"in English and"管理者"in Chinese (ZH superseded 2026-09-18, was"成员"with deliberate organization-member overlap). The stored/token value remainsmember.
Pre-catalog fallback audit
| Site | Decision | Rationale |
|---|---|---|
ensure_agent_selection_access missing-row fallback |
Include member via has_role("member") |
A historical backend-name selector is Agent entitlement compatibility, not Owner identity. |
ensure_agent_name_access legacy task/watch binding fallback |
Keep is_instance_owner |
The fallback preserves executable pre-catalog definitions; a member-created binding is new data and must reference a real catalog Agent because execution deliberately requires that row. |
ensure_session_agent_access backend-only session fallback |
Include member via has_role("member") |
Dispatching a persisted pre-catalog session is compatibility for Agent use/management, not ownership or migration control. |
_require_agent_onboarding_access |
Keep is_instance_owner |
Onboarding inventories and claims every policy-less Agent in one one-way migration; its instance-wide migration authority is distinct from per-Agent management. |
The remote-Owner task/watch write fallback can still admit a missing legacy name while ScheduledTaskService._require_execution_agent_access requires a catalog row at execution. That divergence predates this change and is a known latent issue outside this alignment's scope; it does not justify admitting new member-created bindings. New routing must reference a real Vibe Agent catalog row.
Current-master default semantics
The original follow-up brief referenced the pre-PR-#1606 audience-wide assignment predicate. PR #1606 had already replaced that model on master: an instance default is advisory, and ACL enforcement occurs per principal when the default is resolved. This alignment deliberately preserves #1606. A member may assign a private or scope-policy Agent as the default; a principal who cannot use it degrades to another usable Agent without changing the configured default or widening the target ACL.
Addendum: Agents page load 403s (2026-08-21, post-#1621)
Divergence found
After #1621 aligned the Agent ACL layer, a remote member opening /agents still
got two instance_access_forbidden toasts. Mutation worked; the page load
fired two Owner-only GETs. Both are capability/HTTP mismatches, not ACL gaps:
AgentsPage.refreshOnboardingwas gated oncan_manage_agents. #1621 made that bit true formember, so the page began requestingGET /api/agent-onboarding— a route deliberately kept Owner-only because bulk onboarding is a one-way instance-wide migration. The handler'scatchswallowed the throw, butApiContext.handleApiErrorhad already toasted.- The Agents detail panel auto-selects the default Agent on first load and
loads that backend's model catalog:
GET /api/claude/models,GET /api/codex/models, orGET /api/backend/opencode/providers. None was named by any policy table, so all three fell to the Owner default-deny.
Decisions
Onboarding UI keys off
is_instance_owner, notcan_manage_agents. The route stays Owner (addendum above,_require_agent_onboarding_access); the UI now matches it, so the banner simply never loads for a member and cannot- The member keeps New Agent, Import, Global prompts, edit, and default — all already member-tier.
The Claude and Codex model catalogs are editor-tier, added to
_EDITOR_HTTP_RULESas exact GET rules. Editor rather than member because Chat'sAgentRoutePickershares the same loader and is an editor surface; member inherits editor by rank. Deliberately not an/api/backendnamespace: the rest of that namespace is credential and host work —*/auth*, custom-provider writes, CLI install, runtime restart — and keeps Owner by the unknown-route default. Both arebackend_model_snapshotreads of a shared catalog: no provider configuration in the body, no backend contact on the request.OpenCode gets no editor-tier catalog, and the picker degrades instead.
GET /api/backend/opencode/providersstays Owner. It is not separable from the Settings surface in either direction: its rows carry provider base URLs, masked API-key previews, the active auth type, and the instance tool-call permission setting, and serving it runs_opencode_get_server()→ensure_running(), which installs the caller-context plugin, may restart or terminate the running daemon, and starts one if none is up.Two alternatives were tried and rejected. A
{id, name, models}projection over the same call removes the disclosure but keeps the host-lifecycle effect. Probing health first does not help either:get_providers()and its siblings each callensure_running()themselves.So the model picker reads the Owner-only endpoint best-effort, through
readOpencodeProvidersForModelPicker, which declaresinstance_access_forbiddenan expected code. A lower rank gets no OpenCode suggestions and types the model id — what it already did before the member rank existed, minus the toast.getOpencodeProviderskeeps its loud 403 for Settings, where a refusal is a genuine incident.Follow-up (not this change): give OpenCode a daemon-free catalog snapshot the way Claude and Codex have one.
vibe/backend_model_catalog.pysupports only those two today, andvibe/data/backend_models.jsoncarries no OpenCode entries, so there is nothing to serve without the daemon. Once a snapshot exists, the picker reads it at editor tier and the degradation above goes away.
Rule this leaves behind
A capability bit is the UI's permission to render a surface; the HTTP policy is what may be called. When a rank gains a capability, every request the surface issues on load has to be re-checked against the policy tables, including the shared read-only lookups a page pulls in indirectly. A UI gate that is merely close to the route's tier produces a toast on every page load.