---
slug: platform/workspaces
title: Workspaces
kind: reference
surface: platform
summary: Reference for Aetherfy workspaces — the namespace that groups agents sharing secrets, collections, a region scope and mutual HTTP discovery, plus immutable names, per-tier limits, and the creation and deletion error codes.
sources:
  - aetherfy-control-plane:api/routes/workspaces.py
  - aetherfy-control-plane:shared/error_codes.py
  - aetherfy-control-plane:shared/plan_validator.py
  - dashboard/pages/api/dashboard/workspaces/[name]/regions.js
  - dashboard/migrations/077_add_max_workspaces.sql
  - vectordb:backend/middleware/resolveWorkspaceScope.js
---

# Aetherfy workspaces

## What an Aetherfy workspace is

An Aetherfy workspace is a named namespace that groups agents which share
secrets, collections and mutual discovery. An agent belongs to at most one
workspace. Agents with no workspace at all are equally valid — a workspace is
something you adopt when several agents need to share state, not a mandatory
container.

## What an Aetherfy workspace scopes

A workspace in Aetherfy scopes three things:

| Scope | Effect |
|---|---|
| Secrets | Workspace-level secrets are shared by every agent in the workspace |
| Regions | A workspaced agent's deployment must fall within the workspace's region scope |
| Collections | Collections carry a workspace association |

Everything else about an agent — its memory, its image, its schedule — remains
per-agent. Region rules by tier are covered at `/platform/regions`.

## How Aetherfy agents in a workspace find each other

Agents in the same Aetherfy workspace can reach each other over HTTP. For each
peer, Aetherfy injects an environment variable of the form
`AETHERFY_AGENT_<NAME>_URL` holding that agent's address. You read the variable
rather than hard-coding a hostname, because the address is assigned by Aetherfy
at deployment time.

## Aetherfy workspace names are immutable

A workspace name in Aetherfy cannot be changed after creation. To "rename" one,
delete it and create a new workspace with the name you want — and note that
deletion has preconditions, described below.

Only the description is mutable.

## Errors when creating an Aetherfy workspace

| Condition | Status | Code |
|---|---|---|
| A workspace with that name already exists | 409 | `WORKSPACE_NAME_TAKEN` |
| The region list was supplied but empty | 422 | `WORKSPACE_REGIONS_EMPTY` |
| A region is invalid, or there are more regions than your plan allows | 400 | `INVALID_WORKSPACE_REGIONS` |
| On a single-region plan, the region does not match the account home region | 422 | `STARTER_REGION_CONSISTENCY` |

Operations naming a workspace that does not exist on your Aetherfy account —
reading it, adding secrets to it, deploying into it — return 404
`WORKSPACE_NOT_FOUND`. And when an Aetherfy agent belongs to a workspace, its
deployment regions must be a subset of that workspace's regions; a deploy that
falls outside the scope is rejected with 403 `DEPLOY_REGIONS_NOT_IN_SCOPE`.
Widen the workspace first, or deploy the agent into regions the workspace
already covers.

`WORKSPACE_REGIONS_EMPTY` is specifically about an explicitly empty list.
Omitting the field entirely is a different thing: Aetherfy then picks defaults
bounded by your plan.

## Deleting an Aetherfy workspace

Aetherfy blocks deletion while the workspace still holds resources:

| Condition | Code |
|---|---|
| The workspace still has agents | `WORKSPACE_HAS_AGENTS` |
| The workspace still has collections | `WORKSPACE_HAS_COLLECTIONS` |

Once deletion succeeds, Aetherfy deletes the workspace's secrets. It does
**not** delete vector collections — those must be cleaned up separately, and
their data survives the workspace that referenced them.

## How many workspaces each Aetherfy tier allows

| Tier | Maximum workspaces |
|---|---|
| Free | 1 |
| Starter | unlimited |
| Performance | unlimited |
| Enterprise | unlimited |

Exceeding the limit returns HTTP 400 from Aetherfy with the code
`WORKSPACE_LIMIT_EXCEEDED`.

## Managing Aetherfy workspaces

| Surface | Where |
|---|---|
| Dashboard | `https://app.aetherfy.com/dashboard/workspaces` |
| CLI | `afy workspaces` — see `/cli/workspaces` |

## Workspace-scoped collection routes in the Aetherfy vector API

The Aetherfy vector API exposes collection routes scoped to a workspace, under
`/api/v1/workspaces/{workspace}/collections/...`. The request and response
shapes for those routes are documented at `/vectors/api`.