> This page is for version 0.9.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo-helix/latest/llms.txt
> - 0.9: https://docs.nvidia.com/nemo-helix/v0.9/llms.txt
> - 0.8: https://docs.nvidia.com/nemo-helix/v0.8/llms.txt
> - 0.7: https://docs.nvidia.com/nemo-helix/v0.7/llms.txt
> - 0.6: https://docs.nvidia.com/nemo-helix/v0.6/llms.txt
> - 0.5: https://docs.nvidia.com/nemo-helix/v0.5/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo-helix/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo-helix/_mcp/server.

# Workspaces

Workspaces are the fundamental organizational and authorization boundary in NeMo Helix. All platform resources—models, datasets, customization jobs, evaluation results, and more—must belong to a workspace.

When authentication is enabled, users are granted roles (Viewer, Editor, or Admin) within specific workspaces, and all resources within a workspace inherit its access controls.

Create separate workspaces when you need true isolation—for example, to separate teams (`team-ml-research`, `team-nlp`), individual users (`user-jsmith`), environments (`dev`, `staging`, `production`), or clients (`client-acme`). For lighter-weight organization within a workspace that does not require access separation, use projects.

## Built-in Workspaces

The platform automatically creates two built-in workspaces during initialization:

* **`default`** — General-purpose workspace for experimentation, editable by all authenticated users.
* **`system`** — Reserved for platform-provided resources (for example, evaluation targets, customization templates). Read-only for regular users; only platform administrators can modify.

## Workspace creation on login

When you sign in to Studio through the direct OIDC flow, it checks for a workspace named after your email prefix—for example, `alice` from `alice@example.com`. If the workspace is missing or inaccessible, Studio attempts to create it. Creation requires workspace creation permission, and the creator becomes the workspace Admin. If creation is denied, Studio shows an error but login still completes.

Studio repeats this check on subsequent direct OIDC logins, so a deleted workspace may be recreated.

## Create a Workspace

To create a workspace, provide a `name` and optionally a `description`. The `name` must be unique within your deployment.

Resource names must follow these rules:

* Must start with a lowercase letter (`a`-`z`)
* 2-63 characters long
* Allowed characters: lowercase letters, digits, hyphens, and temporarily `@`, `.`, `+`, `_`
* No consecutive hyphens (`--`)
* Cannot end with a hyphen

**Example valid names:** `my-model`, `llama-3.2-3b`, `test-config-v1`

Once created, a workspace cannot be renamed—choose the `name` carefully. The `description` is a free-form text field to help identify the workspace's purpose.

The system also generates a unique `id` (UUID) for internal use, but the `name` is the primary identifier used in API paths and SDK calls.

By default, any authenticated user can create a workspace because NeMo seeds a wildcard `WorkspaceCreator` role binding in the `system` workspace. The creator still automatically becomes `Admin` of the new workspace.

To restrict workspace creation, remove that wildcard `WorkspaceCreator` binding and grant the role only to the users or groups that should retain create access. This changes creation policy without changing the API surface.

#### Python SDK

```python
from nemo_helix_plugin.client.client import NemoClient
from nemo_helix_plugin.workspaces.types import CreateWorkspaceRequest

client = NemoClient.from_config()

workspace = client.workspaces.create_workspace(
    body=CreateWorkspaceRequest(
        name="ml-team", description="Machine Learning Team workspace"
    ),
).data()
```

#### CLI

```bash
nemo workspaces create ml-team \
    --description "Machine Learning Team workspace"
```

## Restrict Workspace Creation

Workspace creation is now governed by RBAC instead of a hardcoded policy exception. The default seed creates this binding:

```text
principal: *
workspace: system
role: WorkspaceCreator
```

To restrict workspace creation:

1. Remove the wildcard `WorkspaceCreator` binding from `system`.
2. Grant `WorkspaceCreator` only to the users or groups that should create workspaces.

Example:

```bash
nemo workspaces members update "*" \
  --workspace system \
  --roles Viewer

nemo workspaces members create \
  --workspace system \
  --principal ml-leads@bigcorp.com \
  --roles WorkspaceCreator
```

Updating the wildcard member to `Viewer` preserves the seeded read-only access on `system` while revoking `WorkspaceCreator`.

## List Workspaces

To list workspaces, call the list endpoint. When authentication is enabled, only workspaces the user has access to are returned. The response includes pagination metadata.

#### Python SDK

```python
from nemo_helix_plugin.client.client import NemoClient

client = NemoClient.from_config()

for workspace in client.workspaces.list_workspaces().items():
    print(f"{workspace.name}: {workspace.description}")
```

#### CLI

```bash
nemo workspaces list
```

## Get a Workspace

To retrieve a specific workspace by its `name`:

#### Python SDK

```python
from nemo_helix_plugin.client.client import NemoClient

client = NemoClient.from_config()

workspace = client.workspaces.get_workspace(name="ml-team").data()
```

#### CLI

```bash
nemo workspaces get ml-team
```

## Update a Workspace

To update a workspace, only the `description` field can be modified. The `name` cannot be changed after creation.

#### Python SDK

```python
from nemo_helix_plugin.client.client import NemoClient
from nemo_helix_plugin.workspaces.types import UpdateWorkspaceRequest

client = NemoClient.from_config()

workspace = client.workspaces.update_workspace(
    name="ml-team",
    body=UpdateWorkspaceRequest(
        description="Updated: ML Team workspace for model development"
    ),
).data()
```

#### CLI

```bash
nemo workspaces update ml-team \
--description "Updated: ML Team workspace for model development"
```

## Delete a Workspace

Deleting a workspace revokes access immediately and asks an asynchronous cleanup controller to delete the remaining resources (jobs, deployments, filesets, and other entities). Role bindings are removed as part of that first step. The API returns `Workspace marked for deletion`, and the workspace disappears from get and list responses. Its name stays reserved until cleanup finishes.

If cleanup cannot delete a resource, the attempt is recorded and retried about every 60 seconds. A fileset that another workspace's model or adapter still references is the common case: the files service returns 409, and the workspace stays in the `failed` stage with that error. Creating the same name then returns `409` saying the workspace `is still being deleted`, including the stored reason, instead of `already exists`.

The original creator, a platform admin, or a service principal can read that status:

```bash
nemo workspaces deletion-status team-a
```

To free the name, relink or delete the referencing model or adapter, then wait for the next cleanup retry.

#### Python SDK

```python
from nemo_helix_plugin.client.client import NemoClient

client = NemoClient.from_config()

client.workspaces.delete_workspace(name="ml-team").data()
```

#### CLI

```bash
nemo workspaces delete ml-team
```