Workspaces & limits

A workspace is the tenant boundary. Skills, secrets, artifacts, memory, agents and activity all belong to exactly one workspace, and an API key is scoped to one — agents cannot reach across workspaces.

How many workspaces you can create

Your plan sets how many workspaces you may own. Only workspaces you created count; workspaces you were invited into do not.

Two consequences worth knowing before you hit them:

• You get one workspace when you sign up. It is created for you, and it counts toward your limit. A BYOK account is therefore at its limit immediately and cannot create a second workspace.
• Joining is never refused for your plan. You can accept an invitation to any workspace, whatever mode you are on and however many workspaces you already own: the owner’s plan carries it.

Being in more workspaces does not give you more compute. Concurrency is per-user: you hold at most one running execution at a time regardless of how many workspaces you belong to.

How many members a workspace can have

A workspace holds up to 100 members. This is a property of the workspace, not of any one member’s plan, so when it is full the fix belongs to the workspace owner — upgrading your own plan will not let you in.

Execution concurrency

Three limits apply to every run, in this order:

The per-workspace share exists so no single tenant can starve the others. A workspace only approaches it when that many of its members are running something at the same time, because each user holds at most one run.

If your team regularly needs more than its share, write to [email protected] — the share is a fleet setting, not a plan limit, and we would rather hear about it than have you queue.

If you downgrade or cancel

The limit is checked when you create a workspace, so downgrading does not remove you from anything. If you owned ten workspaces on Based Mode and drop to BYOK, you keep access to all ten — nothing is deleted and nothing is revoked.

What changes is headroom: you cannot create another until you are back under your plan’s limit. GET /api/v1/workspaces/usage reports this as overLimit:

{ "used": 10, "joined": 10, "limit": 1, "mode": "byokmode", "canCreate": false, "overLimit": 9 }

Two ways back under, and both stay open — resubscribe, or delete or transfer workspaces you no longer need. The platform will not choose for you, because it cannot know which of your workspaces matters.

When you hit a limit

Every refusal is an HTTP 403 with a machine-readable code in error.details.reason:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You have reached the limit of 1 workspaces for your plan.",
    "details": { "reason": "WORKSPACE_LIMIT" }
  }
}

Branch on details.reason, never on the message text — the wording may change or be translated.

Checking your usage before you act

GET /api/v1/workspaces/usage returns your current position so a client can show the limit rather than discover it on a failed write. used is the number you own; joined is every workspace you belong to, owned or not, and is not what the limit counts:

{ "used": 1, "joined": 3, "limit": 1, "mode": "byokmode", "canCreate": false, "overLimit": 0 }

limit: 0 means uncapped (a site license).

Joining automatically with a GitHub organisation

A workspace owner can name a GitHub organisation in the workspace settings (PATCH /api/v1/workspaces/:workspaceId with githubOrg, or null to turn it off). People who sign in with GitHub and belong to that organisation join the workspace as member when they sign in. Owners and admins are never changed.

• Only an organisation you administer can be set. When you save it, we check with GitHub that your own GitHub account is an active admin of that organisation. The workspace is bound to the organisation’s permanent GitHub id, not its name, so renaming the organisation does not change who joins, and naming one you do not administer does not work. Without a GitHub sign-in on your account, or if GitHub cannot be reached, the save is refused. An organisation can be linked to one workspace at a time.
• If the setting was saved before this check existed, it admits nobody until an owner saves it again.
• Sign-in asks GitHub for the read-only read:org permission, which only lets us see which organisations you belong to. It grants no write access and no access to code.
• If you leave the organisation, the membership that was added automatically is removed at your next sign-in. People who were invited by hand are never removed this way.
• Someone who is removed from the workspace, or who leaves it, is not added back by the automatic sync. They must be invited again.
• After changing the setting, the owner can apply it to their own membership of that workspace without signing in again with POST /api/v1/workspaces/:workspaceId/github-org/sync. It reconciles only that workspace.
• Joining a workspace, automatically or by invitation, never counts against your workspace limit.

Roles and invitations

• You can remove a member, or change their role, only if they rank strictly below you: an admin can manage members but not other admins or the owner. The owner can manage every other member; the owner’s own role changes only by transferring ownership.
• An invitation link carries its inviter’s authority, so it stops working if the inviter has since been removed or demoted below the role it grants. Removing, or demoting, someone also revokes the pending invitations they sent (a demoted inviter loses those above their new role).
• A link issued before someone left or was removed cannot be used by them to rejoin; they need a new invitation.