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:

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

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:

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

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

Managing Aetherfy 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.