Skip to content

Spec: Team mode — Host Members, roles and audience containment #4137

Open
0 of 1 issue completed
Open

Description

@DoodleBears

Problem Statement

A Host serves one Human. Teams want one Host (an office computer or a VPS) to serve several people, each signing in as an independent identity with private Bots, while collaborating with other Humans and Bots in shared Channels so Bots become colleagues who accumulate team context. Today the only Human ID is the hard-coded local-human; PersonaBots have no owner, approvals go to "the Human", Paired Device grants bind no person, and Tob reads everything.

This is orthogonal to the Environment work (#4108 / hub #4109): Environment is one Human across several Hosts; Team mode is one Host serving several Humans.

Solution

An always-multi-member data model in which the existing Human is the Host Owner, plus a Team mode switch that admits Host Members and requires every non-local Client to sign in. Host-owned identity (local password now, OIDC-ready), device grants bound to exactly one Human ID, a fixed Host Permission catalog with Host Roles, advisory Role Policy reusing Behavior permission items, and hard audience containment for Bots, Channels, Workspace roots, approvals and Bot–Bot DMs. Per-member Activity, push and Tob.

Normative decisions: ADR-0336. Design narrative and Q1–Q35 log: team-mode.md (中文). These docs are on branch claude/stoic-euler-25n60k and are not yet on main.

User Stories

  1. As a Host Owner, I want to turn on Team mode and set my password, so that others can use this Host as themselves.
  2. As a Host Owner, I want to create a member with a one-time password and an invitation link/QR, so that onboarding needs no email.
  3. As a Host Member, I want to open the Host's web page on the office LAN and sign in without installing anything, so that I can start immediately.
  4. As a Host Member, I want to be forced to change my initial password and later change it myself, so that only I know it.
  5. As a Host Member, I want to sign in from my phone and computer and pair another device from a signed-in session, so that I use the Host anywhere as myself.
  6. As a Host Member, I want to see only the Tobs Client, not DSH-native sessions or settings, so that other people's work is not exposed.
  7. As a Host Member, I want to create private Bots and have my own Tob, so that my work stays mine.
  8. As a Host Member, I want to browse public Channels and join explicitly, so that I choose what reaches my Activity.
  9. As a Host Member, I want to DM another Human, so that the team needs no separate IM for basic messages and files.
  10. As a Channel owner, I want to control who adds members, posts, @mentions all, adds Bots and edits details, so that I can run announcement or restricted groups.
  11. As a Host Owner, I want to restrict a Bot or Channel to specific roles, so that a finance Bot is unreachable by non-finance members.
  12. As a Host Owner, I want to define roles with permissions and natural-language Role Policy items, so that Bots behave appropriately per person.
  13. As a Host Member, I want to see approval requests in place but only decide those I may decide, so that approvals don't leak content.
  14. As a Host Member, I want a personal Workspace root, so that my Bots work on my files and no one else's Bot can be granted them.
  15. As a Host Owner, I want to view any private content with an audit trail and a member notice, so that oversight is accountable.
  16. As a Host Owner, I want to see usage per member and limit models per role, so that shared compute is understood.
  17. As a Host Owner, I want to reset passwords, revoke devices, deactivate, transfer and finally delete members, so that offboarding is safe.
  18. As a Host Owner, I want to turn Team mode off without losing data, so that the choice is reversible.
  19. As a headless operator, I want every member, role, Channel visibility, audit and Team mode operation in the deepseekbot CLI with local --as <member>, so that verification needs no UI.

Implementation Decisions

Summarised from ADR-0336, which is normative:

  • Model. Always multi-member; local-human is the Host Owner. Team mode is a policy switch, not a second code path.
  • Identity. The Host is the identity authority. Identity and Member Credentials are stored separately; local username/password (argon2id) first, OIDC later. No Better Auth session layer, no Connect dependency, no cross-Host directory sync.
  • Grants. A device grant is (device, Host, Human ID); one active identity per Host per Client. Existing grants bind to the Owner when Team mode is enabled.
  • Access. Local Desktop, loopback and CLI act as the Owner by default, with an option to require a password. Non-loopback password sign-in only over HTTPS or the encrypted gateway; plain HTTP refused unless the Owner enables a warned exception. The API Gateway denies DSH-native methods to members by default.
  • Roles. A unique, transferable Owner. Host Roles over a fixed Host Permission catalog with union semantics; built-in Admin and Member. Role Policy reuses Behavior permission items (Allow/Deny, Deny wins) and is advisory, not access control. Private-content viewing is audited and disclosed to members.
  • Audience containment. Bot visibility private/roles/shared; Channel visibility public/roles/private with Feishu-style Channel admin settings; Human–Human DM; personal and shared Workspace roots, refusing grants into other members' roots, any Memory repository or the Host data directory; Bot–Bot DMs readable only by the participating Bots' owners.
  • Approvals. Cards stay in place and are masked for non-approvers. Opaque-tool approval is limited to Owner/Admin; the dangerous preset is Owner-only.
  • Per member. Activity, read state, push and Tob are per member; usage is attributed per member and Bot.
  • Execution isolation (amended 2026-11-14, research PR docs(team): execution isolation research and settled Team mode scope (M12) #4182). DSH's sandbox restricts writes only, so a member Bot's Shell can read the whole Host. Team mode first opens as a light trial: one plain notice that member Bots can technically read other Bots' data on this Host, and no per-call Shell approval. M12 adds Linux execution confinement (a bwrap wrapper hiding DSH_HOME and other spaces, plus a network namespace) and is required before Team mode leaves the trial. macOS Team Hosts stay on the trial notice.
  • Spaces. A member's personal Workspace root is their account space. Shared roots are audience-scoped shared spaces (for example shared/team, shared/finance). A shared Bot's Memory lives in its shared space, in a bots/ folder kept apart from the grantable files/ folder. Highly sensitive data is best kept on a separate Host (documentation advice).
  • Lifecycle. Deactivate → transfer → separately confirmed purge. Disabling Team mode suspends members and keeps data.
  • Relationships. Host Relationships and same-account enrollment stay Owner-scoped.

Testing Decisions

  • A real Host with the Owner and two members. Prove both successes and refusals through the Client, the Gateway, the CLI with --as, and Bot tool calls.
  • Cross-member isolation regressions: private Bot, private Channel, DMs, Bot–Bot DM, Workspace root, approval content, Activity and push.
  • Existing single-Human behavior is unchanged while Team mode is off (the M0 gate).
  • Security: brute-force limits, reset revokes grants, plain-HTTP refusal, invitation fingerprint mismatch, suspended member refused.
  • Performance: before/after real journeys, at least three interleaved runs per side, for Activity and Channel listing.

Out of Scope

  • Per-member OS accounts or containers; macOS and Windows execution confinement; microVMs. (Linux execution confinement is in scope as M12.)
  • OIDC/SSO and a cross-Host directory.
  • Quotas (including per-account CPU, memory or disk), and an "ask" Role Policy value.
  • Per-object permission overwrites beyond visibility.
  • A remote member CLI.
  • Members inheriting Host Relationships.
  • Merging or releasing as a consequence of publishing this specification.

Activity

  1. DoodleBears commented on Nov 14, 2026

    @DoodleBears
    ContributorAuthor

    Amendment: Bot access model (Human decision, Vain, 2026-11-15)

    Supersedes the "audience containment for Bots" parts of this spec and of M7. Bots are first-class participants like Humans, but every Bot acts for one principal (its creator, or the person who now owns it).

    1. People. Owner > members. The built-in Member role grants only dm.humans (M13 Team mode M13: minimal default member role and Host-only Tob #4187). Creating Bots is split into two Host Permissions, both off for members by default: create private Bots and create public Bots.
    2. Bots inherit from their principal. A Bot's access = its principal's access ∩ restrictions the principal sets on it (nesting only narrows). The Owner and holders of all-Bots management can restrict any Bot further. When the principal loses access (removed from a Channel, a role revoked, offboarded) the Bot loses it at the same moment. Audited private-content viewing (M11) is never delegated to Bots, including the Owner's.
    3. Channels: read or in. A Bot can read any Channel its principal can access (per-Bot switch, see 5). To write it must be in the Channel (added by someone allowed). There is no "silenced" state.
    4. Public vs private only decides who besides the principal may DM the Bot and add it to Channels: nobody (private), or an audience of everyone / roles / specific members (public). Making a Bot public, or widening its audience, requires "create public Bots". Shrinking the audience shows a preview, then removes the Bot from Channels that only people outside the new audience could have added it to, and outsiders' existing DMs become read-only.
    5. Per-Bot switches set by the principal: may proactively DM people in its audience (members can opt out per Bot); may join Channels the principal is in (default on). Adding a Bot to a Channel requires the adder to be allowed to add Bots there, the Bot's principal to have access to that Channel, and that switch to be on.
    6. Behaviour is people + model, not code. Anyone in a Channel can @ a Bot that is in it. Whether a sensitive Bot (e.g. finance) shares a Channel with people outside a role is decided by whoever adds it and by its persona/instructions; there is no hard co-occupancy block.
    7. DMs. Each Human has their own DM with a public Bot; the Bot's principal cannot read other people's DMs with it except through M11 audited viewing. A Bot's single Memory remembers all of its conversations (disclosed when made public).
    8. Bot–Bot. A private Bot may message and delegate to public Bots its principal can reach; public Bots cannot proactively reach private Bots.
    9. Channel access follows its basis. Access granted through a role ends when the role is revoked; access granted to a person by name (M14 invitation) stays until they are removed.
    10. The Owner's Tob is a private Bot under the same rules (no Owner-level shortcut for members).
  2. DoodleBears commented on Nov 14, 2026

    @DoodleBears
    ContributorAuthor

    Product principle (Vain, 2026-11-15): one product, gated by permissions.

    A member's experience is the same as the Owner's for most of the product. The Owner's extra power is deciding what each member can and cannot access — like the AWS console:

    • Every feature exists for everyone.
    • Someone with full access sees and uses all of it, exactly as the Owner does.
    • A member or a limited role simply does not see some panels, cannot reach some objects, and cannot use some features.

    Consequences for the remaining slices:

  3. DoodleBears commented on Nov 14, 2026

    @DoodleBears
    ContributorAuthor

    Mental model (Vain, 2026-11-15): Team mode works like Slack. Joining a Host is joining a workspace. The Owner sets up Channels and who can see them, grants access to members, and people coordinate and manage work by messaging in Channels and DMs. Combined with the permission principle above: a workspace where everyone has the same app, and the Owner's role and permission settings decide what each person sees.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions