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:

• Apps and connectors — each workspace has its own set of installed MCP bundles and connectors
• 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 of the form ws_<16-hex> (for example ws_3f9a1c7e0b2d4856). 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 the ID as opaque: never parse it for meaning. Your personal workspace is the one exception, with a stable ws_user_<userId> form.

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 automations

Creating a workspace

The agent can create workspaces through the nb__manage_workspaces tool. Ask it in chat:

Create a workspace called "Engineering" for our dev team

The agent uses nb__manage_workspaces with action: "create" to set it up. The new workspace gets an opaque ws_<hex> ID; the name you give it is a freely editable label.

Managing members

Add or remove members with the nb__manage_members tool:

Add sarah@example.com to the Engineering workspace as an admin

The tool supports these actions:

Action	Description
add	Add a user to the workspace with a specified role
remove	Remove a user from the workspace
update	Change a member’s role
list	List all members and their roles

Note

Only workspace admins can manage members. Regular members cannot add or remove other users.

Workspace-scoped apps

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

Install @nimblebraininc/tasks in this workspace

The agent installs the bundle and registers its tools in the workspace’s tool registry. Other workspaces are unaffected.

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.

Personal workspaces

Every user has a personal workspace — a private space where you can experiment with apps and conversations without affecting your team. It shows a lock icon in the workspace navigator and uses a stable ws_user_<userId> ID.

Note

NimbleBrain guarantees every authenticated user has at least one workspace. The personal workspace is provisioned on first login and re-created on the next login if it is ever deleted.

Connecting external MCP clients

The /mcp endpoint authenticates you by identity, but each request scopes to one workspace via the X-Workspace-Id header — validated against your membership. tools/list returns that workspace’s tools plus your identity tools, and a tools/call to any other workspace is refused. A request with no X-Workspace-Id exposes identity tools only. See Connecting External Clients for setup.

What’s next

• Conversations — conversations are partitioned by workspace and authorized by owner
• Managing Apps — install and configure bundles per workspace
• Connecting External Clients — connect Claude Desktop, Cursor, and other MCP clients