Workspaces

Workspaces let you organize your NimbleBrain environment into isolated contexts. Each workspace has its own installed apps, connectors, and members. Use workspaces to separate projects, teams, or environments.

What is a workspace?

A workspace is an isolated environment within a NimbleBrain instance. It contains:

• Connectors — each workspace has its own set of installed connectors, and the app UIs they bring with them
• Members — users with assigned roles who can access the workspace

When you send a chat message, it runs in the context of your focused workspace, and the agent’s active tool set is scoped to the apps installed there. Conversations are partitioned by workspace — each one is stored under the workspace it ran in and authorized by its owner. See Conversations for how ownership and storage work.

Note

Workspace IDs are opaque tokens. Every workspace has a generated ID of the form ws_<16-hex> (for example ws_3f9a1c7e0b2d4856); you cannot choose one. The ID is assigned once at creation and never derived from the name — renaming a workspace does not change its ID or its URL. Treat it as opaque: never parse it for meaning.

A directory under workspaces/ whose ID has any other form, such as a name (ws_<name>) or a user ID (ws_user_<id>), is not served: the server skips it and logs a warning naming it. To serve it, rename it to a generated ID — its directory, the id in its workspace.json, and every stored reference to it.

Roles

Every workspace member has one of two roles:

Role	Capabilities
Admin	Can manage members, apps, and connectors.
Member	Can chat and use tools. Cannot manage other members.

What workspaces isolate

Scoped to workspace	Identity-level (cross-workspace)
Installed apps and connectors	Your user account and login
Members and roles	Your profile settings (name, theme, timezone)
Per-workspace credentials
Conversations, files, and tasks
The notification inbox, its source ceilings and its routes

Creating a workspace

An organization admin creates a workspace from Organization → Workspaces → New workspace, or from New workspace in the sidebar’s workspace switcher. Give it a name; it gets a generated ws_<16-hex> ID, and the creator is seated as its admin. The name is a freely editable label: rename it later from the workspace’s Settings → General.

The agent cannot create workspaces. The nb__manage_workspaces tool behind these pages is app-only, so it never appears in the agent’s tool list; it takes no ID or slug and refuses one.

Managing members

Add, remove, and change members from the workspace’s Settings → Members (/w/<id>/settings/members). The page calls the nb__manage_workspaces tool with these actions:

Action	Description
add_member	Add a user, named by userId or email, to the workspace with a specified role
remove_member	Remove a user from the workspace
update_member	Change a member’s role
list_members	List all members and their roles

Note

Every member can see who else is in a workspace. Workspace admins and org admins/owners can manage members: add someone in the organization by email, change roles, and remove people, from the workspace’s Settings → Members. An org admin can manage any workspace’s members without joining it. Regular members cannot add or remove other users. The same people can rename the workspace, from Settings → General.

Workspace-scoped apps

Apps and connectors are installed at the workspace level. When a connector is installed in a workspace, only members of that workspace can use its tools.

A workspace admin installs a connector from the workspace’s connectors catalog (Settings → Connectors). Its tools join that workspace’s tool registry; other workspaces are unaffected. The agent can search the catalog with nb__search and suggest a connector, but it cannot install one.

Deleting a workspace

Deleting a workspace runs the same teardown as removing each connector it holds, one connector at a time, before anything is archived. For every installed connector that means: the app is told it is being removed (on_removing), its OAuth tokens are revoked upstream, a brokered connection is revoked at the broker, its webhook registrations and notification cursors are retired, and its tool permissions are dropped.

Scheduled tasks stop at the same moment. They are disarmed before any teardown begins, so none of them fires against a workspace that is halfway removed, and none of them can write the workspace back onto disk after it is archived.

The workspace’s own data — conversations, files, tasks, and the workspace secrets an operator set — is then archived, not destroyed: the subtree moves to archived/<wsId>/ with a marker file. From every other surface the workspace is gone the moment the delete returns. The archive stays on disk until an org admin purges it from Organization → Archives; nothing purges it automatically.

Each connector’s own credentials are the exception, and go for good: its stored OAuth records and any brokered credential directory are cleared during teardown, because the grant behind them has just been revoked upstream. Archiving a revoked token would keep a secret that no longer opens anything.

Teardown is best-effort per connector. A vendor that cannot be reached does not block the delete; the connector is reported on the result so you know whose grant may still be live and can revoke it in that vendor’s own portal.

Caution

Deleting a workspace requires an org admin. A connector that fails to tear down is named in the result — check it, because once the workspace record is archived nothing in the product points at that grant any more.

Switching workspaces

In the web UI, switch workspaces from the workspace navigator at the top of the sidebar. Your session is identity-bound, so switching is instant — there is no per-workspace session to reset.

Each workspace has a stable URL of the form /w/<id>/.... The agent’s active tools follow your focused workspace; the full set of tools across every workspace you belong to is reachable on demand through nb__search.

Switching lands on the workspace’s Overview. It starts with a box for asking the agent, which sends into the chat panel. Below that are anything that needs attention, your recent conversations in the workspace, and its apps. If you are the only member and can manage members, it also offers to invite people. Workspace admins also get Add app.

Your first workspace

When you first sign in, NimbleBrain creates a workspace for you, named after you (for example, “Mat’s workspace”), with you as its admin. It is an ordinary workspace: add members to share it, rename it, or leave it like any other. Sharing a workspace shares the accounts connected in it with its members.

That workspace is your default — the one you land on when no workspace is open. If you ever belong to no workspace, a new one is created for you the next time you open NimbleBrain.

Connecting external MCP clients

Each workspace has its own MCP endpoint, /mcp/<workspaceId>, shown under Workspace settings → MCP. A client connected to it reaches that workspace’s tools plus your identity tools, only while you are a member, and no other workspace. Bare /mcp is refused. See Connecting External Clients for setup.

What’s next

• Conversations — conversations are partitioned by workspace and authorized by owner
• Connectors — install and configure connectors per workspace
• Notifications — the workspace inbox, and the admin-only settings that decide where an item goes
• Connecting External Clients — connect Claude Desktop, Cursor, and other MCP clients