Skip to Content
PlatformWorkspaces
Raw

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:

ScopeEffect
SecretsWorkspace-level secrets are shared by every agent in the workspace
RegionsA workspaced agent’s deployment must fall within the workspace’s region scope
CollectionsA collection lives in exactly one workspace, and its name is unique there: two workspaces may each have an articles
An agent’s reachAn 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:

PartValue
PeersThe 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
FieldsThe peer’s name and url, and nothing else
ValueThe agent’s public URL — the same url its agent record carries
An agent nothing listens onA 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 globex

Inside 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:

  1. Keep its workspace. Its collections and their data stay exactly as they are, and nothing is deleted.
  2. Remove the grants to it: afy access pdf-processor --remove acme. The agent can no longer reach it, within 60 seconds.
  3. Archive its agents: afy archive <agent> frees the plan slot and keeps the agent’s configuration and code (afy restore brings 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

ConditionStatusCode
A workspace with that name already exists409WORKSPACE_NAME_TAKEN
No regions were named422WORKSPACE_REGIONS_REQUIRED
The region list was supplied but empty422WORKSPACE_REGIONS_EMPTY
A region is invalid, or there are more regions than your plan allows400INVALID_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:

ConditionStatusCode
The workspace still has live agents409WORKSPACE_HAS_AGENTS
The only agents left are still being deleted — retry once that finishes409WORKSPACE_AGENTS_STILL_DELETING
The workspace still has live collections409WORKSPACE_HAS_COLLECTIONS
It is the account’s only workspace409WORKSPACE_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

PlanMaximum workspaces
Free2
Starterunlimited
Performanceunlimited
Enterpriseunlimited

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

Managing Aetherfy workspaces

SurfaceWhere
Dashboardhttps://app.aetherfy.com/dashboard/workspaces  — see Workspaces in the dashboard
CLIafy 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.

Last updated on