Workspaces

Tip

Looking for a quick overview of workspaces in the web UI? See Workspaces in the User Guide.

Workspaces let you organize your NimbleBrain environment into isolated contexts. Each workspace has its own bundles, conversations, 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:

• Bundles — each workspace can have its own set of installed MCP bundles
• Conversations — conversations belong to a workspace and are scoped to its members
• Members — users with assigned roles who can access the workspace

When you send a chat message, it runs in the context of your active workspace. The agent only sees tools from bundles installed in that workspace.

Roles

Every workspace member has one of three roles:

Role	Capabilities
Owner	Full access. Can manage members, bundles, and settings. Cannot be removed.
Admin	Can manage members and bundles. Can view all conversations (including private ones).
Member	Can chat, use tools, and view shared conversations. Cannot manage other members.

Creating a workspace

The agent can create workspaces through the nb__manage_workspaces tool:

Chat

Ask the agent:

Create a workspace called "Engineering" for our dev team

The agent uses nb__manage_workspaces with action: "create" to set it up.

API

curl -X POST http://localhost:27247/v1/tools/call \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "nb",
    "tool": "manage_workspaces",
    "arguments": { "action": "create", "name": "Engineering" }
  }'

Managing members

Add or remove members using 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 (cannot remove the owner)
update	Change a member’s role
list	List all members and their roles

Note

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

Workspace-scoped bundles

Bundles can be 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 selector in the sidebar. Every API request to a workspace-scoped endpoint (/mcp, /v1/chat, /v1/tools/call, /v1/shell, /v1/events) must include an X-Workspace-Id header. Chat requests continuing an existing conversation inherit the workspace from conversationId — no alternative addressing scheme.

Note

NimbleBrain guarantees every authenticated user has at least one workspace. One is provisioned on first login and re-created on the next login if manually deleted. Client code can rely on this invariant — activeWorkspace from /v1/bootstrap is always a valid workspace ID.

Bootstrap

Clients that don’t yet know a workspace ID call GET /v1/bootstrap — the one endpoint where the server picks a default. It returns the authenticated user’s identity, the full workspace list with roles, and the active workspace’s shell configuration. Clients may send X-Workspace-Id on bootstrap as a soft hint (e.g., restoring a user’s last selection from local storage); the server honors it when it matches a membership and falls back to the first workspace otherwise.

What’s next

• Conversations — conversations are scoped to workspaces
• Managing Apps — install and configure bundles per workspace
• Authentication — how users are authenticated