One home, seen whole
Every artifact and folder has at most one workspace home, and every task lives in exactly one workspace — there are no personal or team tasks. Everyone in a workspace sees all of it: files, tables, folders, tasks, outputs, jobs, every agent’s instructions, the history and the trash. Nothing in a workspace has its own setting for who sees it. To keep work private, put it in a separate workspace. Workspace authority runs before every other grant. An artifact with a workspace home uses the workspace’s people instead of standalone team shares, and attempts to team-share workspace content are refused. A write that sendsaudience is refused with 400 INVALID_FIELD and this message: “Sharing is by workspace now: everyone in a workspace sees all of it. Keep private work in a separate workspace.”
Public access is the one step past the members. Any editor can turn on one file’s public link (visibility: link, or Public on the file’s Public link chip in the dashboard): anyone with its URL reads that file alone, with no login and no account, including its earlier versions, so prune them first if they shouldn’t be. The file never appears in listings, search or sitemaps for outsiders, and they see no workspace fields. New, adopted and forked files start private (members only). See Sharing & Access.
Members and roles
Ownership grants access live: the personal owner, or the owning team’s owner and admins, are admins; every other member of the owning team is an editor. Anyone else is a guest you add or invite, as an editor or a viewer. A guest reaches only the workspaces they are added to. To give someone every team workspace, plus the team’s skills and connections, add them to the owning team, where each member is billed. Adding someone who already has access as the owner or through the owning team is refused (WORKSPACE_MEMBER_INTERNAL). An add or role change that sends membership is refused with “Everyone added to a workspace is a viewer or an editor; set role.”
Invite anyone by email. Add an email address, whether or not the person uses Tokenrip. Tokenrip emails them who invited them to what, with your optional note, a link to the invite page and a line to paste into an AI assistant. They sign in with the six-digit code Tokenrip sends to that address, in the browser or through their agent, and they are in: signing in with the address claims every invite waiting on it, with no separate accept step. Until then the members list shows them as invited, with an invite link you can share (it signs no one in). Someone who already uses Tokenrip is added at once; an add by their address tells them by email. Editors share: any editor or admin, guests included, invites people, changes a guest’s role and removes them. A viewer sees the members list without email addresses or pending invites. See Members and Invites.
Admins are on the owner side only; a guest is an editor or a viewer. An agent key limited to a workspace (
read or write) never pins, shares, changes the workspace’s settings or deletes it, even when its person could (KEY_ACCESS_LIMITED).
Creation is attribution, not a grant: someone who made an artifact and later leaves has no access to it. A role change or a removal takes effect on the next request. It stops any task holds the new role no longer allows, clears the person (or their agents) as assignee or reviewer of tasks they can no longer work on, withdraws their open proposals on those tasks, and disconnects their paired browser tabs. A workspace admin may decide any review in the workspace, from their own browser session (a browser an agent’s sign-in link signed in is asked to sign in with email first).
Folders without inheritance
Folders stay flat and grant nothing by themselves. Everyone in the workspace sees every folder and everything in it. Deleting a workspace folder moves it and the artifacts in it to the trash; restoring the folder brings them back filed as they were.Bringing existing content in
Adopt moves an artifact or a normal folder you own into a workspace — atomically, without copying, keeping its identity and versions — and removes its old team shares. Everyone in the workspace then sees it. Public assets and independently hosted content are refused up front. Adoption is the only move direction; there is no move-out.Guarded writes
Two people — or a person and an agent — often edit the same workspace. Existing content writes carry the appropriate precondition: the expected current version id when replacing a document body, the expected row revision for a table row, or the expected workspace revision (a per-item mutation counter) for metadata, filing, schema, and lifecycle changes. New artifact, folder, and task creation needs no expected revision. Insert-only table rows need none; matched upserts retain row revision guards, and any table write may send the table’stableRevision to refuse if anything in the table changed since. A missing required precondition is refused; a stale one returns the authorized current value so the writer can reconcile before a corrected write. The workspace history sequence is never a content precondition. Nothing is ever silently overwritten, and a browser draft is never auto-submitted against newer content.
Why and sessions
Every agent write to workspace content states why: one sentence on what the person is trying to accomplish, in their terms, not a description of the edit. “Set launch prices the team can defend to finance” is a goal; “Update row 4 of the pricing table” is not. The CLI takes--why (or TOKENRIP_WHY), MCP tools and REST writes take a why field, and a write without one is refused with WHY_REQUIRED before anything changes. Moving a task along (start, stop, complete, cancel, reopen, a move in the queue, a later result on a Done task), an output recorded on a task and settling an output need none: the move records its own reason, and a why sent is recorded. A message needs none. Every other call accepts a why too, reads and messages included: it is not saved in the workspace’s history; Tokenrip keeps it only in its log of the call. People editing in the dashboard never state one. Each change records the why, the agent key that made it, the harness, and exactly what it did: created, edited to a new version, rows added or updated, details changed, moved, public access given or removed, and so on.
A session is computed from those changes when someone reads it: a run of changes by one account, through one agent key and one harness conversation, each within 45 minutes of the previous one. Nothing is started, ended, or expired, so there is no ceremony to skip. Each session reads like a git log: who worked (“You” for your own account’s work, or another person and their agent), from which tool, when, and each stated reason followed by the changes made for it: the item, what was done, and the versions it created, with a diff of what the step changed. Sessions with changes you have not acknowledged are marked unread. Loading a workspace returns the latest five; rip workspace sessions (MCP workspace_sessions) pages further back, and each workspace’s Activity in the web app shows the same log, marking what is new since you last marked it read.
Picking up where another agent left off needs no note. The next agent reads the records the work wrote as it happened: the person’s instructions and pins, open tasks (a comment in a stopped task’s thread says how far it got), the whys and sessions, and the files.
What load returns
Loading a workspace reads bounded context for the calling agent key, in the order to read it:
The first load records the agent in the workspace: its handle, used by others to hand it work. Workspace names can repeat: name a workspace by its id or slug. A slug two of your workspaces share is refused with each candidate’s id, so use the id. Every workspace list carries
needsYou: how much waits on the caller there, counted as the web app’s Inbox counts its rows. For an agent key: approved tasks for it to carry out, reviews addressed to it and To do tasks naming it. For a person: reviews addressed to them (or unaddressed, when they may decide), never their own proposal, and To do tasks for them with no agent named. See Load Workspace.
Browser pairing
The operator opens the agent’sbrowserLink in the web app, and that tab follows the agent’s key in this workspace, only within the same account, and only by explicit choice; opening a link elsewhere never steals a pairing. One tab follows a key per workspace. A paired tab publishes its saved context (which artifact and version it shows, whether an edit is in progress), and the agent reads that context before resolving “this document”, then writes by artifact id with the reported precondition. Revoking the key or losing access disconnects the tab.
The agent may ask the tab to open an artifact. The request is applied only while the tab is following and clean; if the person is editing, has paused, or the context moved, it becomes an “Open” offer and the receipt says deferred. Ordinary writes never navigate anyone. The tab polls for committed changes and refreshes what it shows; it never keystroke-mirrors, and a dirty draft is always preserved.
Reading is not polling
Activity in a workspace is an ordered stream, and every member reads all of it. Each reader — every agent key, and the operator’s browser — has its own position. Loading, polling, and reading never move it; an explicit acknowledgment of a delivered page does. If retention has pruned past a reader’s position, the stream says so instead of pretending nothing happened.Lifecycle
- Delete is admin-only and moves the workspace, with everything in it, to the trash for 30 days. It need not be empty. While it is there, every call on it answers
410 WORKSPACE_DELETEDwith the purge date, and its slug stays held. - Restore (
rip trash restore <id>, admin-only) brings it back as it was, until the purge date. - After the purge date the workspace and everything in it are removed for good.
rip trash purge <id>(or Delete forever in the dashboard) removes it for good sooner; it cannot be undone. - Artifacts and folders inside the workspace have the same delete and restore, with the workspace revision as their precondition.
Every surface
Workspaces work the same way from the CLI (rip workspace … plus the ordinary artifact, table, folder, and task commands with workspace flags), the MCP workspace_* tools, the /v0/workspaces REST API, and the dashboard.
CLI reference
Every
rip workspace command, and the workspace flags on other commands.Folders
Flat organization inside and outside a workspace.
The web app
Where the operator works alongside the agent.