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.

A workspace is a wall for Aetherfy agents

The key Aetherfy injects into an agent reaches, on the Aetherfy vector API, only the collections of the agent’s own workspace — or, for an agent with no workspace, the collections in no workspace. Any other workspace is refused to it, 403 AGENT_KEY_WORKSPACE_FORBIDDEN, whether or not the collection exists there. Your own keys are not affected.

When an agent needs another workspace’s collections, grant it that workspace: on the agent’s page in the dashboard, or with afy access <agent> --add <workspace>. A grant belongs to the agent and survives its redeploys; deleting the workspace deletes the grants to it. The rules, and every route, are on what an agent’s key reaches.

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, changing it, deleting it, listing its agents, setting or listing its secrets — return 404 WORKSPACE_NOT_FOUND; deploying into one is refused with 403 WORKSPACE_NOT_FOUND. You name a workspace; Aetherfy looks the name up in your account once and holds on to that workspace, so nothing is ever attached to a name alone. 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. Each condition returns HTTP 409 and names 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.

A workspace created afterwards under the same name is a new workspace. It starts empty: no secrets, no agents, nothing the deleted one held — and no agent that was granted the deleted workspace reaches the new one.

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.