Aetherfy workspaces
What an Aetherfy workspace is
An Aetherfy workspace is a named namespace that groups agents which share
secrets, collections and mutual discovery. Every agent and every collection
lives in exactly one workspace, chosen when it is created. Aetherfy injects the
agent’s workspace id into the agent as AETHERFY_WORKSPACE_ID, and the SDKs’
workspace="auto" reads it.
The default workspace
Every account starts with one workspace, named default, and always keeps at
least one: deleting the last is refused with 409 WORKSPACE_IS_LAST.
While you have a single workspace you never pick it. The dashboard’s create
dialogs pre-select it and the CLI uses it (afy create, afy init, and every
collection, points and index command). Once you have several, the dashboard asks
and the CLI asks too; without a terminal, --workspace <name> is required.
Secrets shared across a workspace
A secret set on a workspace reaches every agent living in it. That is how you
share one secret, say a database URL, across all your agents: put it on default
(or whichever workspace they live in) and set nothing per agent. An agent’s own
secret with the same name wins over the workspace’s, for that agent only.
Aetherfy reads the secrets when it deploys, so a change applies at the agent’s
next deployment: see Secrets.
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 | A collection lives in exactly one workspace, and its name is unique there: two workspaces may each have an articles |
| An agent’s reach | An agent’s key reaches the collections of the workspace it lives in and of the workspaces you grant it access to, and no others |
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, its home, plus the workspaces you grant
it. 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.
An agent holds a level in each workspace it reaches: read, read_write or full.
A grant is read unless you say otherwise, and the agents that live in a workspace
hold the workspace’s default level (read_write), which you can change with
afy workspaces update <name> --agent-access-level or on the workspace’s page. The
levels, the secrets switch and protected collections are on
agent access.
How Aetherfy agents in a workspace find each other
Agents in the same Aetherfy workspace can reach each other over HTTP, and an agent asks for a peer’s address by name, when it makes the call. Nothing about a peer is written into your agent’s environment, so a peer created later, or deleted and created again at a new address, is found by the next lookup without redeploying your agent.
With the Aetherfy SDK helpers:
from aetherfy_agent import agent_url, call_agent
url = agent_url("bench-ranker") # the peer's current public URL
reply = call_agent("bench-ranker", "/rank", method="POST", json={"query": "q"})
print(reply.status, reply.json())import { agentUrl, callAgent } from 'aetherfy-vectors/agent';
const url = await agentUrl('bench-ranker');
const reply = await callAgent('bench-ranker', '/rank', { method: 'POST', json: { query: 'q' } });agent_urls() (agentUrls()) returns every addressable peer as a name-to-URL map.
The helpers read AETHERFY_PEERS_URL, a template like AETHERFY_SPAWN_URL
(.../agents/{id}/peers with a literal {id} for your agent’s own id), and your
agent’s own key. Without the SDK, call the route yourself:
curl -s "${AETHERFY_PEERS_URL//\{id\}/$AETHERFY_AGENT_ID}/bench-ranker" \
-H "Authorization: Bearer $AETHERFY_API_KEY"
# {"name":"bench-ranker","url":"https://bench-ranker-k3m7x2q5hwd4nzra.aetherfy.dev"}What the lookup answers:
| Part | Value |
|---|---|
| Peers | The other live agents of your agent’s own workspace. An agent is not its own peer: asked for by its own name, the answer is the same 404 AGENT_NOT_FOUND, saying so, and an agent’s own address is its AETHERFY_PUBLIC_HOST variable. A name in another workspace or another account, a deleted agent and an unknown name are the same 404 AGENT_NOT_FOUND |
| Fields | The peer’s name and url, and nothing else |
| Value | The agent’s public URL — the same url its agent record carries |
| An agent nothing listens on | A job agent, or one that is not deployed, has no URL: asked for by name it is 409 PEER_HAS_NO_URL, and the list leaves it out |
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.
The helpers keep an answer for 30 seconds per name, and fresh=True
({ fresh: true }) skips that. call_agent looks the peer up again once, and only
when the address it used is gone: the name does not resolve, the connection is
refused, or the edge refuses the address of a deleted agent (404 with
AGENT_NOT_FOUND or AGENT_NOT_REACHABLE). Any other answer is returned as it
came, and a reset or a timeout raises without a repeat, because the peer may already
have acted: give a request that is not safe to repeat its own idempotency key. Your
Aetherfy key goes to the lookup and never to the peer. A lookup counts in your plan’s
requests-per-minute limit like any other call to the agents API, which the 30-second
memory keeps far below, and when a lookup is refused (429, a 5xx, or no connection)
the helper returns the last address it knew for that peer and does not ask again before
the Retry-After it was given (at least 5 and at most 60 seconds), raising only when it
has no address to fall back to.
A stale address never reaches a different agent: each agent’s public address is unique and is never reused, and the old machine is gone. The edge refuses the address of a deleted agent once its list of deleted agents’ addresses has reached it, which takes a little while and is not instant; until then a call to the old address simply fails.
The route is on the Workspaces and regions API, and the key that may call it on API keys.
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.
A workspace per customer: one home, plus grants
If you serve several customers from one agent, give each customer a workspace for its collections, and give the agent a home of its own. A grant lets the agent reach another workspace. It gives access; it does not move the agent.
Say a pdf-processor agent reads each customer’s invoices. It lives in a
workspace called platform, and the customers have acme and globex, each
with its own invoices collection (two collections, one name, because names are
unique per workspace):
afy create pdf-processor --workspace platform
afy access pdf-processor --add acme --add globexInside the agent, workspace="auto" is only the agent’s home, platform.
Code that serves several workspaces names the workspace for each call:
from aetherfy_vectors import AetherfyVectorsClient
clients = {}
def search_invoices(customer, query_vector):
# "auto" would mean the home workspace. Name the customer's own.
if customer not in clients:
clients[customer] = AetherfyVectorsClient(workspace=customer)
return clients[customer].search("invoices", query_vector=query_vector, limit=5)import { AetherfyVectorsClient } from 'aetherfy-vectors';
const clients = new Map();
export async function searchInvoices(customer, queryVector) {
// 'auto' would mean the home workspace. Name the customer's own.
if (!clients.has(customer)) {
clients.set(customer, new AetherfyVectorsClient({ workspace: customer }));
}
return clients.get(customer).search('invoices', queryVector, { limit: 5 });
}A workspace the agent was not granted is refused (AgentWorkspaceForbiddenError),
so an agent can reach only the workspaces you granted it. Only you can
grant access, never the agent itself: see
what an agent’s key reaches.
Closing a customer
When a customer leaves:
- Keep its workspace. Its collections and their data stay exactly as they are, and nothing is deleted.
- Remove the grants to it:
afy access pdf-processor --remove acme. The agent can no longer reach it, within 60 seconds. - Archive its agents:
afy archive <agent>frees the plan slot and keeps the agent’s configuration and code (afy restorebrings it back).
To keep closed customers out of the way, leave each one in its own workspace.
Do not gather them into one shared “archive” workspace: collection names are
unique per workspace, so acme’s invoices and globex’s invoices cannot both
move there, and a move that would clash is refused (409 COLLECTION_NAME_TAKEN)
before anything starts.
The memory SDK’s threads collection never moves
The memory SDK keeps conversations in one collection per workspace, named
__threads__, shared by every agent that lives there. Aetherfy never moves it
(COLLECTION_SDK_MANAGED) and never lets it be renamed: moving it would hand
every agent’s conversations to the agents of another workspace. The same holds
when you move an agent: its conversation history stays in the workspace it
left, and its MemoryClient reads the new workspace’s collection. See
moving an agent.
Renaming an Aetherfy workspace
A workspace can be renamed, and so can its description. A rename keeps
everything in the workspace — its agents, collections and secrets — and from
then on the workspace answers to the new name only. Running agents are
unaffected: they hold the workspace’s id, not its name
(AETHERFY_WORKSPACE_ID). See
the workspace API.
Errors when creating an Aetherfy workspace
| Condition | Status | Code |
|---|---|---|
| A workspace with that name already exists | 409 | WORKSPACE_NAME_TAKEN |
| No regions were named | 422 | WORKSPACE_REGIONS_REQUIRED |
| 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 |
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. 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.
Every workspace owns its regions, so creating one names them: omitting the field is
WORKSPACE_REGIONS_REQUIRED, which lists the regions you can choose from and your
plan’s limit, and WORKSPACE_REGIONS_EMPTY is specifically about an explicitly empty
list. Nothing is chosen for you.
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:
| Condition | Status | Code |
|---|---|---|
| The workspace still has live agents | 409 | WORKSPACE_HAS_AGENTS |
| The only agents left are still being deleted — retry once that finishes | 409 | WORKSPACE_AGENTS_STILL_DELETING |
| The workspace still has live collections | 409 | WORKSPACE_HAS_COLLECTIONS |
| It is the account’s only workspace | 409 | WORKSPACE_IS_LAST |
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
| Plan | Maximum workspaces |
|---|---|
| Free | 2 |
| 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 — see Workspaces in the dashboard |
| CLI | afy workspaces — see afy workspaces |
Workspace-scoped collection routes in the Aetherfy vector API
Every collection route of the Aetherfy vector API sits under a workspace, named
by name (/api/v1/workspaces/{workspace}/collections/...) or by id
(/api/v1/workspace-ids/{workspace_id}/collections/...). The request and response
shapes are documented at REST API reference.