Multi-User Onboarding¶
/user creates and manages canonical users. The former /newuser token is
not an alias and is not accepted. Every person gets a stable
usr_... identity, and that identity owns their conversations, memory,
schedules, attachments, and Web Chat history.
All users open the same /webchat page. Do not create per-user URLs and do not
put a token or invitation code in a URL.
Authenticated Web Chat supports the browser-relevant /user forms:
help, status, list, enable, disable, remove, role, token,
invite, and code.
The signed Web Chat session determines who runs the command; a browser request
cannot supply or impersonate another canonical user.
Commands that bind an external platform identity must be run on that platform.
That includes /user <external_user_id> "Display Name", /user
--replace ..., and /user link <code>. Running one of those forms in Web
Chat returns guidance instead of creating a synthetic browser-channel binding.
What <external_user_id> Means¶
<external_user_id> is the stable sender identifier reported by the chat
platform. It is not the person's display name and usually is not their
username. Use the exact newuser_target=... value from the rejected-message
gateway log when possible.
| Platform | Example external user id | Admin command |
|---|---|---|
| Telegram | 123456789 (from_user.id) |
/user 123456789 "Alice" |
| Discord | 987654321012345678 (numeric user ID) |
/user 987654321012345678 "Alice" |
+15551234567 (normalized E.164 sender) |
/user +15551234567 "Alice" |
|
| Signal | 550e8400-e29b-41d4-a716-446655440000 (sourceUuid) |
/user 550e8400-e29b-41d4-a716-446655440000 "Alice" |
| Photon/iMessage | imessage:+15551234567 (emitted sender ID) |
/user imessage:+15551234567 "Alice" |
See the platform pages for how to find each value: Telegram, Discord, WhatsApp, Signal, and Photon/iMessage.
Onboarding Path 1: Chat Platform, Then Self-Service Web Chat¶
An already bound admin adds Alice from the same chat system Alice will use:
/user 123456789 "Alice"
The first value is Alice's external platform ID. "Alice" is only her display
name. The response includes Alice's new canonical ID, for example
usr_a1b2c3d4e5f6.
Alice can use the chat platform immediately. If she also wants Web Chat, Alice runs this herself from her newly registered chat identity:
/user token "Alice laptop"
"Alice laptop" is a device label. It is not a username or canonical user ID.
The command always creates a token for the identity that runs it; it does not
select a user named Alice. If an admin runs this command, the token belongs to
the admin. The returned uauser_... token is immediately active and shown
once. Alice stores it securely, opens https://agents.example.com/webchat, and
pastes the token into the form. Its lifetime follows
gateway.users.web_user_token_ttl_days; the default 0 means it does not
expire automatically.
Onboarding Path 2: Admin Invite for an Existing User¶
An admin can enroll an existing canonical user into permanent Web Chat access:
/user list
/user invite usr_a1b2c3d4e5f6 --label "Alice laptop"
The usr_... value comes from /user list. The label describes the intended
browser or device. The response returns:
- the shared
/webchataddress; - a single-use
uainvite_...code; - the invitation lifetime.
Send the address and code through a trusted channel. Alice opens /webchat and
pastes the code into the form. The invitation is consumed and Alice sees a
blocking Finish Setting Up Web Chat popup. She selects Generate, copies
the new uauser_... token, stores it somewhere safe, and selects I've Saved
My Token. Only that final confirmation activates the permanent token and
unlocks Chat.
Onboarding Path 3: Web-Only User¶
When Alice will use only Web Chat and has no Telegram, Discord, WhatsApp, Signal, or Photon identity, an admin creates the canonical user and initial invite together. The admin may run this directly in authenticated Web Chat:
/user invite --new "Alice" --label "Browser Onboarding"
"Alice" is the display name. "Browser Onboarding" is the invitation label.
The new user receives a usr_... identity and active team membership but no
channel binding. Give Alice the returned /webchat address and one-time
uainvite_... code. Alice follows the permanent-token popup described above.
The generated token inherits the "Browser Onboarding" label.
Alice is a durable team member as soon as the command succeeds. The invitation
is only an enrollment credential; the generated uauser_... token is her
reusable Web Chat credential.
Settings When Adding Someone¶
Both ways of adding a person (/user <external_user_id> "Name" and
/user invite --new "Name") take these options:
--team-keysor--own-keys: whether their work may use the team's model keys. With--own-keys, agents use only the model they set up themselves with/auth model me, and their requests do not run until they do. Without either, the team's model-key sharing decides: shared (the default) lets them use the team's keys, private does not. Owners and administrators change it with/accounts share modelor/accounts private model(see Shared or private); it applies only to people added afterwards. Change one person later with/user team-keys <usr_...> on|off(owners and administrators only).--shared <name>: a shared working folderteam/<name>for their work, for example--shared research-notes. Everyone also hasteam/team-shared. Folders underteam/are open to the whole team: their agents, your agents and the team's own agents can all read and write them. Use a person's own folder (users/...) for anything private.
The reply ends with a report of how the person is set up:
Settings for Alice (usr_a1b2c3d4e5f6):
- Role: member
- Added through: telegram identity 123456789
- Timezone: America/Chicago
- May use the team's model keys: no (change with /user team-keys usr_a1b2c3d4e5f6 on)
- Own model: not set up yet. Their requests do not run until they set it up with /auth model me
- Personal folder: users/usr_a1b2c3d4e5f6
- Shared folders: team/team-shared, team/research-notes (open to the whole team: ...)
/user status shows the same model and folder lines for the person who runs
it. See Model Keys for how people set up
their own model.
First-Time Setup¶
When the team keeps something private, the person you add brings their own. The report above ends with what they still have to set up, for example:
- Still to set up: their own model (needed) and optionally their own GitHub (gh), X (xurl) (/setup lists them)
- First message: they are shown what is still to set up for themselves.
The First message line appears only when the first-time setup was recorded for them; a person who is restored or added again gets none. The person sees that list on their first message:
- Their own model, when they may not use the team's model keys and have
not saved one. It comes first, because their requests cannot run without
it. Their first message is held back and the list is the reply; they send
/auth model me, keep Use this as my model ticked, and send their message again. - Their own account for each private service someone in the team uses:
every service the team keeps private
(Shared or private), GitHub and
Google included, that the team or another person already has an account
for. A service nobody in the team uses is left out;
/link <tool_id>still works for it, and a task that needs it says so. These are optional. Each line names the command that opens the secure page, such as/link http:exaor/link cli:github, and how the page ended comes back in the same chat.
When the model is not needed, the list arrives as a separate message that
says their message is on its way, and their first message goes to the team as
usual. When there is nothing to list, they see no list at all. The list is shown once; /setup
shows what is still left at any time. Later messages are never held: if the
model is still missing, the reply says so and names /setup. People who were
in the team before this existed are not shown a first-time setup, but /setup
works for them too.
Returning to Web Chat¶
The browser uses a 12-hour HTTP-only session cookie. Alice does not need to
re-enter her token while that session remains valid. After logout, session
expiry, a gateway restart, or moving to another browser, she opens /webchat
and enters her saved uauser_... token. Her existing owner-scoped conversations
and gateway-owned Web Chat transcripts return after authentication.
If Alice refreshes after generating a token but before confirming that she saved it, the raw token cannot be shown again. The popup offers Generate Replacement; the abandoned pending token is revoked and never becomes usable. If she loses an already activated token, an admin can issue another enrollment invitation for her existing canonical identity:
/user invite usr_a1b2c3d4e5f6 --label "Replacement browser token"
Onboarding Path 4: Link the Same Person to Another Platform¶
Link codes attach an additional platform identity to an existing canonical user. They do not create a second person.
Alice runs this from a channel already linked to her account or from her authenticated Web Chat session:
/user code
The gateway returns a value similar to:
Link code for usr_a1b2c3d4e5f6: AbCdEf1234
Expires at UTC: 2026-07-30T18:30:00+00:00
AbCdEf1234 is a short-lived, one-time proof that the new platform identity
should belong to Alice's existing usr_... user. It is stored only as a hash,
expires after gateway.users.link_code_ttl_seconds (15 minutes by default),
and is consumed by the first successful link. It is not a Web Chat token and
cannot authenticate at /webchat.
Alice then sends the returned code from her own identity on the other platform. This second command cannot be run in Web Chat because the destination platform's sender identity is what must be bound:
/user link AbCdEf1234
The gateway binds the sender ID supplied by that second platform to the same canonical user that created the code. Alice's conversations from both platforms therefore belong to Alice while remaining isolated from every other team member.
The person who owns the existing identity must generate the code. Do not use
an admin's own link code to onboard a new person; it would attach the new
platform identity to the admin's canonical user. If the destination identity
is already linked, /user link AbCdEf1234 --replace is required to rebind
it.
Roles¶
Every person has one role in the team:
| Role | Who | What it allows |
|---|---|---|
owner |
Whoever set up the instance; there can be more than one | Everything an administrator can do, and making someone an owner or changing an owner's role |
admin |
Team administrators | Adding, disabling, removing, and inviting people, changing roles other than owner, and giving, removing, and blocking agents' access to the team's tools |
member |
Everyone else | Their own conversations, memory, schedules, and logins |
The instance's user (user.canonical_user_id in instance_config.yaml)
becomes the first owner when the gateway creates their membership. Owners and
administrators change a role with /user role:
/user role usr_a1b2c3d4e5f6 admin
/user role usr_a1b2c3d4e5f6 member
/user role usr_a1b2c3d4e5f6 owner
- Only an owner makes someone an owner or changes an owner's role.
- The team always keeps at least one owner and at least one administrator; a change that would remove the last one is refused.
- The new role applies from the person's next action, because roles are read again at every access decision.
- Every change is recorded with who made it (
team_role_changeingateway_user_events).
Instances set up before owners existed. The gateway does not change an
existing membership, so the instance's user stays an admin. While a team
has no owner, an administrator may name one, for example themselves:
/user role <your usr_... id> owner.
Administration and Verification¶
Run these from an already bound owner or admin identity, or an authenticated owner or admin Web Chat session:
/user status
/user list
/user list active
/user list disabled
/user list removed
/user disable usr_a1b2c3d4e5f6
/user enable usr_a1b2c3d4e5f6
/user remove usr_a1b2c3d4e5f6
/user role usr_a1b2c3d4e5f6 admin
/user list shows canonical IDs, where each person stands in the team
(active, disabled, removed from the team, or not a member of this
team), memberships with their roles, bound channel identities, default
notification targets, and last-seen times. /user list active, disabled,
and removed show only the people who stand that way. User-facing times are
converted from canonical UTC storage into the authenticated requester's
configured IANA timezone and rendered with a readable date, clock time, and
timezone abbreviation.
Disable or remove¶
Disable is for a pause you intend to undo:
- It immediately prevents new chat-platform and Web Chat requests, including requests from an existing browser session.
- Their running and queued work is cancelled, their objectives stop (they are kept, paused), their schedules are deleted, and access requests waiting for them or made for their work are withdrawn.
- The person stays on the team. Their folder, memory, conversations, access grants, linked accounts, their GitHub, Google and X sign-ins and channel bindings are kept.
/user enablerestores access. The person must sign in to Web Chat again, and their own memory review and knowledge review schedules are installed again; the schedules deleted when they were disabled do not come back.- Only an owner can disable or enable an owner, and nobody can disable themselves.
Remove is for someone who left:
- Everything that disabling does happens, and they are taken off the team: they can no longer use it from any chat app or Web Chat.
- Deleted at once: their task records (running, stopped, paused and finished) and objectives, their chat sessions and Web Chat history, their sign-ins, the access grants for their work and the access grants they gave (including what they shared from their folder), their personal account links and the credentials stored under them, their own GitHub, Google and X sign-ins and the broker's private credentials folder for them, their requests and notices, their starter-profile choice, their memory-review jobs and their personal OpenShell sandbox. The reply names the sign-ins that were deleted. The team's credentials and sign-ins are not touched.
- Held, then deleted: their private folder (including their Python
environments), their personal memory, their own knowledge pages and their conversations move out of
every agent's reach for
gateway.users.removed_data_retention_days(7 days by default). The reply to/user removesays until when. After that time a maintenance run deletes them. - Kept: audit records (
gateway_user_eventsand the access event log), what they put in the sharedteam/andagents/folders, and files they sent to other people. - The runtime's own team schedules (for example the maintenance schedule and the team memory audit) are never deleted with a person. When their owner is disabled or removed they move to another active administrator, and administrators get an Inbox notice. They continue in new conversations, as do the heartbeat checks: the earlier conversation history stays with the person who left and comes back with them if they are restored. If preparing the heartbeat checks for their new owner fails, they stay stopped until the cleanup succeeds on a retry.
- Only an owner can remove an owner, nobody can remove themselves, and the team always keeps at least one owner and one administrator.
- Running
/user disableor/user removeagain for the same person checks their work and records again; use it when the reply says something could not be done.
Restore brings a removed person back with their held data:
/user restore usr_... (owners and administrators) adds them back as a
member, moves their folder, memory and conversations back, and installs their
memory-review schedules. Their tasks, schedules and objectives do not come
back, and neither do their stored credentials and sign-ins, which were
deleted at once: they sign in again with /link. After the hold ends,
/user restore explains that the data is gone.
/user enable does not apply to a removed person. Adding them back the usual
way, /user <external_user_id> "Display Name" from the chat app they used or
/user invite usr_... for Web Chat, makes them the same person with the
member role again (and enabled, if they had also been disabled). While their
data is still held, it comes back as with /user restore; after that, they
start fresh.
Web Chat Security and Separation¶
- A reusable
uauser_...token and a one-timeuainvite_...code are secrets. Neither is stored in browser local storage or placed in a URL. - Invitation codes are stored only as hashes, expire after
gateway.users.web_user_invite_ttl_seconds(15 minutes by default), and can be used once. - Permanent tokens are also stored only as hashes and are shown once. During
the popup they remain
pendingand cannot authenticate until the user confirms that the token was saved. - Pending tokens expire with the enrollment session. Generating a replacement revokes the prior pending token.
- Permanent tokens do not expire by default. Operators can set
gateway.users.web_user_token_ttl_daysto impose an expiration policy. - The browser uses an HTTP-only, same-site session cookie. It is marked
Securewhennetwork.public_originuses HTTPS. - Server sessions, gateway transcript rows, and attachment references are scoped by canonical user. Browser storage contains only disposable UI state, not the authoritative message list. Logging out and signing in as another user switches to that user's isolated history.
- Each person's files live in their own folder under
workspaces/users/. Agents working for one person, and the shell and Python commands they run, cannot open another person's folder, and nobody can give access to it. In OpenShell mode each person's code runs in their own sandbox. See Files and folders.
Storage and Restart Behavior¶
Users are durable gateway state, not static instance_config.yaml entries. The
gateway stores:
gateway_usersgateway_user_channel_bindingsgateway_user_team_membershipsgateway_user_web_tokensgateway_user_web_invitesgateway_user_link_codesgateway_user_eventsgateway_transcript_streamsgateway_transcript_session_sequencesgateway_transcript_messages
Direct-user registration, token creation, invitations, role changes, disabling, and enabling take effect immediately. No restart is required. Static adapter changes—such as enabling a platform, changing credentials, or changing a group/channel allowlist—still require config reload or restart.