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

# Workspaces

<a id="workspaces" />

Workspaces are the fundamental organizational and authorization boundary in NeMo Platform. 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.

## 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.

```python
import os
from nemo_platform import NeMoPlatform

client = NeMoPlatform(
    base_url=os.environ.get("NMP_BASE_URL", "http://localhost:8080"),
    workspace="default",
)

workspace = client.workspaces.create(
    name="ml-team", description="Machine Learning Team workspace"
)
```

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

## 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
import os
from nemo_platform import NeMoPlatform

client = NeMoPlatform(
    base_url=os.environ.get("NMP_BASE_URL", "http://localhost:8080"),
    workspace="default",
)

response = client.workspaces.list()
for workspace in response.data:
    print(f"{workspace.name}: {workspace.description}")
```

```bash
nemo workspaces list
```

## Get a Workspace

To retrieve a specific workspace by its `name`:

```python
import os
from nemo_platform import NeMoPlatform

client = NeMoPlatform(
    base_url=os.environ.get("NMP_BASE_URL", "http://localhost:8080"),
    workspace="default",
)

workspace = client.workspaces.retrieve("ml-team")
```

```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
import os
from nemo_platform import NeMoPlatform

client = NeMoPlatform(
    base_url=os.environ.get("NMP_BASE_URL", "http://localhost:8080"),
    workspace="default",
)

workspace = client.workspaces.update(
    "ml-team", description="Updated: ML Team workspace for model development"
)
```

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

## Delete a Workspace

Deleting a workspace removes the workspace and all of its resources (jobs, deployments, filesets, role bindings, and other entities). The API returns immediately after revoking access, and an asynchronous cleanup controller handles deletion of the remaining resources in the background.

During cleanup, the workspace is no longer visible to users. If cleanup fails, the workspace enters a `FAILED` state that requires administrator attention.

```python
import os
from nemo_platform import NeMoPlatform

client = NeMoPlatform(
    base_url=os.environ.get("NMP_BASE_URL", "http://localhost:8080"),
    workspace="default",
)

client.workspaces.delete("ml-team")
```

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