docs: document Warp's native workspaces model #723
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| --- | ||
| title: Workspaces | ||
| description: >- | ||
| Workspaces group multiple teams under one enterprise account, with | ||
| company-wide roles, billing, and settings that sit above each team's own | ||
| configuration. | ||
| --- | ||
|
|
||
| A workspace is Warp's top-level organizational unit for enterprise accounts. It groups one or more teams under a single company account, with its own roles, billing, and governance settings that apply across every team inside it. | ||
|
warp-agent-staging[bot] marked this conversation as resolved.
|
||
|
|
||
| {/* VERIFY: confirm current plan-tier availability for native (multi-team) workspaces; billing config shows it enabled only for Warp's own internal enterprise plan as of this writing */} | ||
|
warp-agent-staging[bot] marked this conversation as resolved.
|
||
| Multi-team workspaces are an Enterprise-plan capability, currently available to a limited set of accounts. Self-serve and Business plans keep the single-team model described in [Team management](/knowledge-and-collaboration/teams/): the workspace still exists underneath, but it always contains exactly one team, so the team remains the only management surface you see. | ||
|
There was a problem hiding this comment. Do we need this paragraph? We already mentioned that workspaces is a unit for enterprise accounts. Feel like this is duplicative? |
||
|
|
||
| ## Workspace vs. team | ||
|
|
||
| A **team** is Warp's collaboration unit: members share a Warp Drive, cloud agent runs, environments, and secrets, and a team admin can configure team-level settings. A **workspace** is the account-level container above one or more teams. On an enterprise workspace with multiple teams: | ||
|
|
||
| * Billing (the service agreement, credit pool, and spend caps) attaches to the workspace, not to any single team. | ||
| * Company-wide governance settings — like secret redaction or AI autonomy limits — are configured once at the workspace level instead of being copied across teams. | ||
| * A user is a member of the workspace first, and of zero or more teams inside it. | ||
|
Comment on lines
+18
to
+20
There was a problem hiding this comment. We can also say SSO (Single Sign-On) is governed on the workspace level too |
||
|
|
||
| ## Workspace roles | ||
|
|
||
| Every workspace member has one of three roles: | ||
|
|
||
| * **Member** - Default role. Uses Warp within whatever teams they belong to and the settings admins configure. | ||
| * **Admin** - Manages workspace membership, billing, and settings. A workspace can have any number of admins. | ||
| * **Owner** - The workspace's single highest-privilege role. Has every admin capability, plus the ability to transfer ownership to another member. There's always exactly one owner, and they can't be removed or demoted without first transferring ownership. | ||
|
|
||
| {/* VERIFY: confirm a workspace admin's admin-level permissions extend to teams they don't belong to in the shipped client; specs/workspace-admin-roles invariants 18-19 define it, but changelog #15123 confirms only membership management on the admin's own team */} | ||
| A workspace admin or owner has admin-level permissions on every team in the workspace, even ones they don't belong to. A team's own admin retains full control of that team, but no authority outside it. In the team members list, a workspace-level admin or owner carries a **Workspace admin** or **Workspace owner** badge, so members can tell a company-wide admin apart from a team-only one. | ||
|
|
||
| ## Teams inside a workspace | ||
|
|
||
| Workspace admins create teams from the Admin Panel, giving each one a name, a color, and a visibility: | ||
|
|
||
| * **Open** - Any workspace member can see the team and join it immediately. | ||
| * **Private** - Any workspace member can see the team exists, but joining requires an admin to add or invite them directly. {/* VERIFY: requesting to join a Private team isn't live yet per specs/team-joining-flows; confirm current UI before publishing */} | ||
|
There was a problem hiding this comment. Yeah private teams aren't ready yet; let's remove this for now |
||
| * **Hidden** - The team doesn't appear in team discovery; an admin has to add members directly. | ||
|
|
||
| Both workspace admins and a team's own admins can rename a team, change its color or visibility, and manage its members and its deletion. Only workspace admins can create a new team. A workspace member can belong to more than one team at a time. | ||
|
|
||
| {/* VERIFY: confirm the team Owner role stays hidden on multi-team workspaces in the shipped client; specs/team-crud deprecates it in favor of workspace-level ownership and drops the Owner chip and transfer-ownership action, but no public changelog entry confirms it */} | ||
| A team itself has two roles, member and admin. Ownership belongs to the workspace rather than to any one team, so the [Team Owner role](/enterprise/team-management/teams/#team-roles-and-permissions) of the single-team model doesn't apply here. | ||
|
Comment on lines
+43
to
+44
There was a problem hiding this comment. I don't think it's worth mentioning the fact that the team owner role is deprecated. I think we can just remove this whole blob ngl |
||
|
|
||
| ## Joining a workspace or team | ||
|
|
||
| New members reach a workspace and its teams through a few paths: | ||
|
|
||
| {/* VERIFY: confirm the workspace-level invite link and domain capture flows are live, not just specced */} | ||
|
There was a problem hiding this comment. workspace level invite links and domain capture flows are live, so can remove this comment |
||
| * **Invite links** - An Open team's invite link adds someone directly to that team, and to the workspace if they're not already in it. A workspace-level invite link additionally lets a new member pick an open team as part of accepting. Private and Hidden teams don't support invite-by-link — an admin adds those members directly. | ||
|
There was a problem hiding this comment. Yeah let's not mention private teams here yet |
||
| * **Email invites** - A team or workspace invite addressed to a specific email instead of shared as a link — the way to add someone to a Private or Hidden team. | ||
|
|
||
| * **Domain capture** - When a workspace admin enables it for a verified company domain, anyone who signs up with a matching work email is automatically added to the workspace. | ||
| * **Team discovery** - Anyone who lands in the workspace without a team, from any of the paths above, sees a list of open teams they can join with one click in the Warp app under **Settings** > **Teams**. | ||
|
|
||
| {/* VERIFY: confirm a user can belong to only one workspace at a time in shipped behavior; specs/team-joining-flows treats it as an invariant, but no public source states it */} | ||
| A user belongs to at most one workspace at a time. | ||
|
Comment on lines
+56
to
+57
|
||
|
|
||
| ## Teamless members | ||
|
|
||
| A workspace member isn't required to belong to a team. This "teamless" state is meant to be temporary — for example, right after joining the workspace and before an admin places them on a team. | ||
|
warp-agent-staging[bot] marked this conversation as resolved.
|
||
|
|
||
| A teamless member is still a full workspace member: the workspace's plan, billing, and governance settings continue to apply to them, and workspace admins can see and manage them from the Admin Panel. {/* VERIFY: confirm the exact current scope of teamless-member restrictions (cloud agent runs, environments, secrets, scheduled agents) against shipped behavior */} What they lose access to is team-scoped collaboration: joining a team is required to trigger cloud agent runs or use team-owned environments and secrets — this applies to workspace admins and owners as well, even though they keep their workspace-level oversight in the Admin Panel. | ||
|
Comment on lines
+59
to
+63
There was a problem hiding this comment. Can you call "teamless members" as "unassigned users" instead? I think that's the term we're using externally Also can you mention that workspace admins can set the spend limit for unassigned users separately on the admin panel?
Comment on lines
+59
to
+63
There was a problem hiding this comment. and yes, teamless users/unassigned users cannot trigger factory/oz/cloud runs |
||
|
|
||
| ## Workspace settings and team settings | ||
|
|
||
| Settings that used to live only on the team — AI autonomy, secret redaction, sharing, codebase indexing, and similar policies in the [Admin Panel](/enterprise/team-management/admin-panel/) — now resolve across the workspace and team layers on a multi-team workspace. Each setting follows one of four patterns: | ||
|
|
||
| {/* VERIFY: confirm the four setting-resolution patterns and the examples assigned to each against shipped behavior; sourced from specs/multi-team-workspace-settings, with no public source */} | ||
| * **Workspace-enforced** - The workspace admin sets one value that applies to every team; team admins can't override it. Billing caps, the credit pool, and domain capture always work this way. | ||
| * **Delegated ("respect team setting")** - The workspace admin can either enforce a value or leave it to each team to decide, the same way a delegated team setting can respect each user's own preference. | ||
| * **Combined** - Entries from both levels apply together. A blocked-commands list is a union — an entry from either level takes effect; an allowed-commands list is an intersection — only entries present at both levels apply. | ||
| * **Team-controlled** - The workspace layer never touches this setting. Custom model configuration and enabled agent harnesses stay team-only. | ||
|
Comment on lines
+69
to
+73
|
||
|
|
||
| When a workspace enforces a setting, team admins see it locked with an indicator that the workspace controls it. | ||
|
|
||
| ## Workspace spend limits | ||
|
|
||
| On a multi-team workspace, an optional workspace-level spend cap sits above the [team-level spend limits](/enterprise/support-and-resources/billing/#monthly-spending-limits) and any per-user limits. All three levels are independent and optional, and whichever cap is hit first blocks further usage in its scope: | ||
|
|
||
| {/* VERIFY: confirm cap precedence and the per-role spend visibility rules, including the generic blocked-by-workspace-cap notice, against shipped behavior; sourced from specs/workspace-spend-limits */} | ||
| * **Workspace cap** - Blocks every team in the workspace. | ||
| * **Team cap** - Blocks only that team. | ||
| * **Per-user limit** - Blocks only that person. | ||
| * **Spend visibility** - Workspace admins see spend at every level. A team admin sees only their own team's usage, plus a generic notice when a workspace-level cap is the one that blocked them. | ||
|
|
||
| ## Related pages | ||
|
|
||
| * [Team management](/knowledge-and-collaboration/teams/) - Creating and joining a team | ||
| * [Admin Panel](/enterprise/team-management/admin-panel/) - Configure settings enforced across a workspace or team | ||
| * [Roles and permissions](/enterprise/team-management/roles-and-permissions/) - Team-level roles and what each can do | ||
| * [Enterprise billing](/enterprise/support-and-resources/billing/) - Credit pools, spend limits, and billing management | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This feels a bit wordy, maybe something like this?