---
slug: dashboard/workspaces
title: Workspaces in the dashboard
kind: reference
surface: dashboard
summary: Reference for the Workspaces area of the Aetherfy dashboard — listing, creating and deleting workspaces, editing a description, a workspace's regions and its agents — with every label it shows and the afy CLI and REST equivalents.
sources:
  - dashboard/src/app/(authenticated)/dashboard/workspaces/page.tsx
  - dashboard/src/app/(authenticated)/dashboard/workspaces/[name]/page.tsx
  - dashboard/src/components/workspaces/WorkspaceAgents.tsx
  - dashboard/src/components/regions/WorkspaceRegionsSettings.tsx
  - dashboard/src/components/regions/RegionChangeInProgress.tsx
  - dashboard/src/components/regions/RegionNarrowConflictPane.tsx
  - dashboard/src/components/ui/TypedConfirmModal.tsx
  - dashboard/src/lib/agents/agent-status-colors.ts
  - dashboard/src/lib/billing/workspace-limit.js
  - dashboard/src/lib/billing/nudge-copy.js
  - dashboard/src/components/billing/PlanLimitNotice.tsx
  - dashboard/src/lib/health.ts
---

# Workspaces in the Aetherfy dashboard

## What the Aetherfy dashboard's Workspaces area is

The Workspaces area of the Aetherfy dashboard, at
[app.aetherfy.com/dashboard/workspaces](https://app.aetherfy.com/dashboard/workspaces),
lists your workspaces and opens one at a time to show its regions and its agents.
What a workspace is and what it scopes is explained at
[Workspaces](/platform/workspaces).

The page follows your plan's workspace limit ([limits](/platform/workspaces)): every
plan sees its workspaces here, Free included, which holds one. At the limit,
**CREATE_WORKSPACE** is disabled and the page offers the next plan — the same limit
the API and `afy` enforce.

## Aetherfy workspace labels

| Label | Meaning |
|---|---|
| `NEW WORKSPACE` | The create form: a name (lowercase and hyphens, 3 to 63 characters), an optional description, and regions |
| `NO WORKSPACES YET` | You have no workspace |
| `PLAN LIMIT REACHED` | You hold as many workspaces as your plan allows; **CREATE_WORKSPACE** is disabled, and the link offers the next plan |
| `WORKSPACE REGIONS` | On a workspace's page: the regions its agents and collections may use. Performance and above |
| `REGION CHANGE IN PROGRESS` | A region change on this workspace is already running; **CHECK STATUS** re-reads it |
| `Workspace was not updated.` | Removing a region was refused because agents or collections still use it. The list names each one and what to do: redeploy the agent with new regions, or change the collection's regions |
| `AGENTS` | On a workspace's page: the agents in it, with their status (the [agent statuses](/dashboard/agents)) and endpoint |
| `No agents in this workspace yet.` | No agent belongs to this workspace |
| `DEGRADED` | Beside an agent: a multi-region deploy still converging |

On a single-region plan the create form shows your account's home region, read-only:
the workspace lives there.

## Aetherfy workspace actions

| Action | CLI | REST |
|---|---|---|
| **CREATE_WORKSPACE** | `afy workspaces create` ([workspaces](/cli/workspaces)) | `POST /api/v1/workspaces` ([workspaces API](/agents/api-workspaces)) |
| Edit the description | `afy workspaces update` | `PATCH /api/v1/workspaces/{workspace}` |
| Change the workspace's regions — **APPLY** | — | `PATCH /api/v1/workspaces/{workspace}/regions` |
| List its agents | `afy workspaces agents` | `GET /api/v1/workspaces/{workspace}/agents` |
| Delete — type the workspace's name to confirm | `afy workspaces delete` | `DELETE /api/v1/workspaces/{workspace}` |

Deleting an Aetherfy workspace also deletes every secret scoped to it, and those
values cannot be recovered. Deleting a workspace that still has agents stops
before the confirmation, with a message saying how many to delete first. A workspace that still
holds collections is refused with `WORKSPACE_HAS_COLLECTIONS`.

## What the Aetherfy dashboard does not do for workspaces

| Not in the dashboard | Where instead |
|---|---|
| Rename a workspace | Not possible in Aetherfy: names are immutable. Create a new one |
| Move an agent into or out of a workspace | Set `workspace:` in the agent's `aetherfy.yaml` and deploy, or `afy update <agent> --workspace` ([updating](/cli/agents)) |
| Move a collection into a workspace | The collection's placement tab, in the [Database area](/dashboard/database) |
| Set a workspace secret | The [Secrets area](/dashboard/secrets) |