Workspaces
Create OpenShell workspaces, assign members, and understand platform and workspace roles.
An OpenShell workspace is an access and resource isolation boundary. Sandboxes, sandbox workload templates, providers, provider profiles, services, policies, and settings belong to a workspace and are not visible to members of other workspaces.
The CLI targets the default workspace unless you set --workspace or
OPENSHELL_WORKSPACE. The logical OpenShell workspace described here is
separate from the /sandbox filesystem directory inside a sandbox.
For Kubernetes namespace mapping and managed per-workspace namespaces, see Workspace on Kubernetes.
Understand the Role Model
Section titled “Understand the Role Model”OpenShell combines an identity-provider role with a membership record for each workspace.
| Role | Assignment | Access |
|---|---|---|
| Platform Admin | The OIDC role configured as admin_role. |
Manages platform-scoped configuration and every workspace. Platform Admins bypass workspace membership checks. |
| Workspace Admin | An admin membership stored by the gateway for one workspace. |
Manages providers, provider profiles, policies, settings, and members in that workspace. |
| Workspace User | A user membership stored by the gateway for one workspace. |
Creates and uses sandboxes and services, reads providers, and uses provider attachments in that workspace. |
OIDC users also need the role configured as user_role for ordinary workspace
operations. The configured Platform Admin role satisfies this requirement.
Membership does not grant access to another workspace, and a Workspace Admin
cannot perform platform-scoped or cross-workspace operations.
When the gateway enables scope enforcement through scopes_claim, the token
must also contain the scope required by the operation. Common scopes include
workspace:read, workspace:write, sandbox:read, sandbox:write,
provider:read, provider:write, config:read, config:write,
secret:read, and secret:write.
openshell:all satisfies every scope requirement. For OIDC and scope
configuration, refer to Gateway Authentication.
The following table summarizes common operations.
| Operation | Platform Admin | Workspace Admin | Workspace User |
|---|---|---|---|
| Create or delete a workspace | Any workspace | No | No |
| View a workspace or list workspaces | All workspaces | Assigned workspaces | Assigned workspaces |
| List workspace members | Any workspace | Assigned workspace | Assigned workspace |
| Add Workspace Users or remove members | Any workspace | Assigned workspace | No |
| Assign the Workspace Admin role | Any workspace | No | No |
| Create, use, or delete sandboxes and services | Any workspace | Assigned workspace | Assigned workspace |
| Create or delete sandbox workload templates | Any workspace | Assigned workspace | No |
| Read or list sandbox workload templates | Any workspace | Assigned workspace | Assigned workspace |
| Create, update, or delete providers | Any workspace | Assigned workspace | No |
| Change workspace policy or settings | Any workspace | Assigned workspace | No |
| Manage platform profiles or global configuration | Yes | No | No |
| List resources across workspaces | Yes | No | No |
Inspect Your Identity
Section titled “Inspect Your Identity”Use the identity validated by the gateway when an administrator needs your membership subject.
openshell whoamiopenshell whoami --output jsonThe subject field is the stable identity used in workspace membership
records. Each user can run this command even when they do not belong to a
workspace.
Create a Workspace and Add Members
Section titled “Create a Workspace and Add Members”A Platform Admin creates workspaces and assigns the first Workspace Admin.
The gateway creates the default workspace automatically, but it does not add
OIDC users to that workspace automatically.
Create a workspace:
openshell workspace create --name team-mlAsk the intended Workspace Admin to run openshell whoami, then add the
reported subject:
openshell workspace member add \ --workspace team-ml \ --subject 'oidc-subject-for-admin' \ --role adminThe Workspace Admin can add Workspace Users:
openshell workspace member add \ --workspace team-ml \ --subject 'oidc-subject-for-user' \ --role userOnly a Platform Admin can assign the admin membership role. A Workspace
Admin can add user members and remove members in their assigned workspace.
List and Remove Members
Section titled “List and Remove Members”All members can inspect membership in their workspace. Workspace Admins and Platform Admins can remove members.
openshell workspace member list --workspace team-ml
openshell workspace member remove \ --workspace team-ml \ --subject 'oidc-subject-for-user'Add --output json or --output yaml to list membership records for
automation. Each record contains subject and a normalized role of admin,
user, or unknown. Structured output is an envelope with members and
next_page_token fields; pass the returned token to --page-token to
continue. An empty result has an empty members collection.
To change a member’s role, remove the existing membership and add it again
with the new role. A Platform Admin must perform any change to admin.
Label and List Workspaces
Section titled “Label and List Workspaces”Attach labels when you create a workspace to track environment or team ownership.
Repeat --label for each key-value pair.
openshell workspace create --name team-research --label env=dev --label team=mlList workspaces that match every key-value pair in a comma-separated selector. Filtering only returns workspaces you are authorized to view.
openshell workspace list --label-selector env=dev,team=mlInspect a workspace to see its labels. Pass --output json or --output yaml
to workspace create, workspace get, or workspace list for structured
output in automation.
openshell workspace get team-researchopenshell workspace get team-research --output jsonopenshell workspace list --label-selector env=dev --output jsonAPI clients set CreateWorkspaceRequest.labels and filter with
ListWorkspacesRequest.label_selector. Returned workspace labels are stored in
metadata.labels. OpenShell does not provide a workspace update operation to
change labels after creation.
Target a Workspace
Section titled “Target a Workspace”Pass --workspace to scope a resource operation. The flag is global, so it
can appear before or after the subcommand.
openshell sandbox list --workspace team-mlopenshell provider list --workspace team-mlopenshell sandbox create \ --workspace team-ml \ --name research \ --from registry.example.com/team/agent-tools:1.0 \ -- bashSet a default for the current shell with OPENSHELL_WORKSPACE:
export OPENSHELL_WORKSPACE=team-mlopenshell sandbox listWhen --workspace is omitted, the CLI intentionally selects the default
workspace. An empty workspace name is invalid and never means either default
or all workspaces.
Platform Admins can opt into cross-workspace list operations:
openshell sandbox list --all-workspacesopenshell provider list --all-workspacesopenshell service list --all-workspacesWorkspace-scoped public requests use the workspace_scope field with a
WorkspaceSelector. Single-workspace requests select a non-empty canonical
name, including the literal default. Only sandbox, sandbox template,
provider, and service collection list requests also accept all_workspaces.
The all-workspaces selection requires Platform Admin access. For services,
choose either a sandbox name or --all-workspaces; the options are mutually
exclusive.
Every sandbox-scoped RPC identifies the sandbox by its human-readable name and keeps workspace selection in a separate field:
{ "workspaceScope": { "workspace": "team-ml" }, "name": "agent"}Public requests do not accept canonical sandbox IDs as references. This is a
breaking API change: regenerate protobuf clients and replace stored ID
references with sandbox names before calling the public API. The four collection
list RPCs use the request-level workspace_scope selector.
The Rust and Python SDKs expose separate all-workspaces list methods. The Go
SDK passes AllWorkspaces: true in ListOptions to ListAll, and the
TypeScript SDK uses a discriminated option type, so a caller cannot select a
named workspace and all workspaces in one typed call.
The TUI starts in the default workspace and sends that name explicitly. Its
all-workspaces collection views send the selector marker instead.
Provider profiles and policy also have explicit --global operations. Those
operations target platform scope and require Platform Admin access. A
Workspace Admin should use --workspace for workspace-scoped profiles and
configuration.
Diagnose Access Denials
Section titled “Diagnose Access Denials”If openshell workspace list returns no rows, the authenticated subject has no
workspace memberships. Run openshell whoami and send the subject value to
a Platform Admin.
Workspace authorization errors include a copyable membership command. A
non-member denial suggests --role user. If an operation requires Workspace
Admin access, the denial suggests --role admin; only a Platform Admin can run
that assignment successfully.
If the membership is correct but the request is still denied, inspect roles
and scopes with openshell whoami --output json. Confirm that the token has
the configured OIDC user role and, when scope enforcement is enabled, the
scope required by the operation.
Delete a Workspace
Section titled “Delete a Workspace”Only a Platform Admin can delete a workspace. The default workspace cannot
be deleted.
openshell workspace delete team-mlA custom workspace must not contain sandboxes, sandbox workload templates, providers, provider profiles, services, SSH sessions, settings, policies, draft policy chunks, or credential refresh state. Remove those resources before retrying deletion. OpenShell removes membership records as part of successful workspace deletion.
Next Steps
Section titled “Next Steps”- To configure OIDC roles and scopes, refer to Gateway Authentication.
- To create resources in a workspace, refer to Manage Sandboxes.
- To manage workspace credentials, refer to Providers.
We are a Cloud Native Computing Foundation sandbox project.
Copyright OpenShell a Series of LF Projects, LLC
For website terms of use, trademark policy and other project policies please see lfprojects.org/policies/.