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. An agent that declares no workspace carries no AETHERFY_WORKSPACE variable, and the Aetherfy SDKs running inside it work against unscoped collections; nothing invents a workspace on its behalf.

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 plan are covered at Regions and replication.

How Aetherfy agents in a workspace find each other

Agents in the same Aetherfy workspace can reach each other over HTTP. For every deployed service agent in the workspace, Aetherfy injects one environment variable into each agent of that workspace, the service itself included:

A job agent has no variable of its own, because nothing listens on its machine. Every agent in the workspace, job agents included, is still named in AETHERFY_WORKSPACE_AGENTS.

Read the variable rather than hard-coding a hostname. Because the value is the agent’s public URL, a request to a peer that has passed its idle timeout resumes that peer; you do not need to wake it first.

Aetherfy writes these variables when it creates a machine for your agent, so a machine keeps the set it was created with. A peer’s URL does not change when the peer is redeployed, so a variable your agent already holds stays correct. A service agent deployed into the workspace for the first time after your agent has no variable in your agent’s existing machines: redeploy your agent to pick it up.

If you call a peer with Python’s standard-library urllib, send a User-Agent header of your own. The library’s default one has been refused at the edge in front of Aetherfy’s API hosts before, and a refusal there reads like an authentication failure.

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. Both conditions return HTTP 409 and name the count that is blocking you:

Deleting a workspace therefore never destroys vector data as a side effect: deletion does not cascade to collections, and a workspace still holding one cannot be deleted at all. Empty it first, through the vector API or SDKs.

Once both conditions hold, deletion removes the workspace record and its workspace-scoped secrets.

How many workspaces each Aetherfy plan 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 REST API reference.