00000000-0000-0000-0000-000000000001) that hosts system-provided and shared resources, including default agents. Additional workspaces can be created to support independent resource management and team collaboration. When you work within a workspace, all operations are scoped to that workspace context.
Workspace functions are available through the orchestrate workspaces command group in the CLI. This command group provides capabilities to create, list, remove, activate, deactivate, and export workspaces, and manage workspace membership.
Workspaces are supported on IBM Cloud and on-premises IBM Software Hub (version 5.4.4 and later).
Workspace context
A workspace must be activated to be used as the current working context. When activated, all subsequent CLI operations are run within that workspace. It includes creating, importing, updating, and listing resources. If no workspace is explicitly specified in a command, the active workspace is used by default.Workspace management
Workspaces can be created or updated by using a single command. Listing workspaces returns all available workspaces within the tenant or service instance and indicates the currently active workspace. Workspaces can also be removed, with options to control how associated resources are handled (delete artifacts or move them to the global workspace). Workspaces can be exported into a ZIP file, which includes all resources within the workspace. This allows workspace resources to be packaged, backed up, or shared across environments.Workspace limits and constraints
- Maximum workspaces: Up to 100 workspaces per tenant or service instance.
- Maximum members: Up to 50 members per workspace.
- Name uniqueness: Workspace names must be unique within a tenant or service instance.
- Minimum ownership: Every workspace must have at least one owner at all times. The last owner cannot be removed or demoted.
Roles and permissions
Access to workspaces and their resources is governed by a combination of platform/instance-level roles and workspace-level roles.Platform and service instance roles
These roles are assigned at the service instance or account level, before workspace membership is considered.- Administrator (IAM Admin on IBM Cloud / Service Instance Administrator on IBM Software Hub): Full administrative access across all workspaces. Can create, view, update, and delete any workspace, manage members, and recover orphaned workspaces.
- Builder (
wxO Builderon IBM Software Hub / standard builder on IBM Cloud): Can self-service create new workspaces. On IBM Software Hub environments, only users assigned thewxO Builderrole are eligible to be added as workspace members. - User (
wxO Useron IBM Software Hub / standard user on IBM Cloud): End users who interact with deployed agents. Users cannot create workspaces or be added as workspace members.
On IBM Software Hub, the
wxO Builder and wxO User roles are assigned by a Service Instance Administrator through the IBM Software Hub user management interface. These are IBM Software Hub service-level roles, not workspace roles. Trusted profiles and IAM access groups are not applicable on IBM Software Hub — see Platform differences.Workspace roles
Workspace roles control what a member can do within a specific workspace. They are assigned when a user is added to the workspace.- Owner: Full management access within the workspace. Can update and delete the workspace, add, update, and remove members, and create, update, and delete all artifacts. The user who creates a workspace is automatically assigned the Owner role. Multiple owners are supported.
- Editor: Can create, update, and delete artifacts (agents, tools, knowledge bases) and view workspace details and members. Editors cannot modify workspace settings or manage members.
Permission matrix
Artifact scope
The same artifact types are workspace-scoped on both IBM Cloud and IBM Software Hub deployments. The following resource types belong to a workspace and are only accessible to workspace members:- Agents
- Tools and toolkits
- Knowledge bases
- Connections
- Channels
Getting started on IBM Software Hub after upgrade
When upgrading to IBM Software Hub 5.4.4 or later from a previous version, the following applies:- All existing agents are placed in the global workspace.
- To restrict access to specific agents, copy them from the global workspace into a new private workspace.
- After copying, you can delete the original agents from the global workspace if you want to prevent other users from accessing them.
- When working across multiple instances, use the ADK to export agents from one instance and import them into another, specifying a target workspace (private or global) in the destination instance.
Platform differences
While the user and CLI experience is consistent across environments, the underlying authorization architecture varies:- IBM Cloud: Access is integrated with IBM Cloud IAM and PDP policies using IAM tokens and access groups. Trusted profiles and access groups are used to manage builder and user roles.
- IBM Software Hub (5.4.4+): Access is managed through Zen Core Resource Object policies scoped to the service instance. Trusted profiles and IAM access groups are not required and do not apply. Workspace membership is restricted to users with the
wxO Builderrole. Roles are assigned through the IBM Software Hub service instance user management interface.
Command structure
Workspace functions are organized under the following CLI structure:orchestrate workspaces– Workspace lifecycle management (create, list, remove, activate, deactivate, export)orchestrate workspaces members– Workspace membership management (add, list, remove)

