afy workspaces
The afy workspaces command group in the Aetherfy CLI
An Aetherfy workspace groups agents so they can share secrets, share vector
collections, and reach each other over HTTP. The command group has two aliases,
workspace and ws.
| Subcommand | Purpose |
|---|---|
afy workspaces create <name> --regions <r1[,r2]> | Create a workspace, with the regions it owns |
afy workspaces list | List all workspaces |
afy workspaces info <name> | Show one workspace in detail |
afy workspaces update <name> | Rename a workspace, change its description, or the level its agents hold in it |
afy workspaces regions <name> --regions <r1[,r2]> | Set the full set of regions a workspace owns |
afy workspaces delete <name> | Delete a workspace and its secrets |
afy workspaces agents <workspace> | List the agents that live in a workspace and the ones granted access to it |
Creating an Aetherfy workspace
afy workspaces create <name> creates a workspace. It takes exactly one
positional argument. A workspace owns its regions: agents and collections in it can
only use those.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--regions | strings | asked on a terminal | The regions the workspace owns: 1 up to your plan’s limit, from the regions your plan allows. Repeat the flag or comma-separate | |
--description | -d | string | empty | Workspace description |
afy workspaces create research --regions us-east-1
afy workspaces create research --regions us-east-1,eu-central-1
afy workspaces create research --regions us-east-1 -d "Shared retrieval corpus and scrapers"The regions are validated before anything is sent, and a refusal exits 2 with
Nothing was created.:
| Refusal | Message |
|---|---|
| A region is not open on your plan | region <r> is not open on your plan (allowed: ...). Nothing was created. |
| A name that is not a region | <r> is not a region (allowed on your plan: ...). Nothing was created. |
| More regions than the plan allows | <n> regions given, but your plan allows <max> per workspace (allowed: ...). Nothing was created. |
| An empty value | --regions got an empty region (allowed: ...) or --regions needs at least one region (allowed: ...) |
No --regions, and not a terminal (a script, or --json) | a workspace owns its regions: pass --regions with up to <max> of: ... Nothing was created. |
On a terminal without --regions, the command asks you to pick from the regions your
plan allows.
The success names the regions the workspace was created with (a Regions line, and
regions under --json).
Aetherfy enforces the name rules server-side:
| Rule | Detail |
|---|---|
| Length | 3–63 characters |
| Character set | Lowercase alphanumeric and hyphens |
| Boundaries | Cannot start or end with a hyphen |
Valid: research, sales-ops, team-2. Invalid: Research (uppercase),
-research (leading hyphen), ab (too short).
Listing Aetherfy workspaces
afy workspaces list prints every workspace in the account. It takes no
arguments and no flags of its own.
afy workspaces list
afy workspaces list --json| Column | Meaning |
|---|---|
| Name | The workspace name |
| Agents | Number of agents assigned to it |
| Description | The description, if set |
| Created | Creation timestamp |
On an account with no workspaces, --json prints [].
Inspecting an Aetherfy workspace
afy workspaces info <name> prints one workspace in detail. It takes one
positional argument and no flags of its own.
afy workspaces info research
afy workspaces info research --jsonFields printed: ID, Name, Description, Regions, Agents, Agent access level, Created, Updated.
Updating an Aetherfy workspace: rename, description or agent level
afy workspaces update <name> renames a workspace, changes its description, sets
the access level its own agents hold in it, or any of them.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--name | string | empty | Rename the workspace | |
--description | -d | string | empty | Workspace description (optional) |
--agent-access-level | string | none | The level the agents living in the workspace hold in it unless set otherwise: read, read_write or full (the default for a workspace is read_write) | |
--yes | -y | bool | false | Raise the agents’ level without asking |
At least one of the three is needed; with none, an empty --name, or a level that is not one of the three,
the command exits 2 before sending anything. Raising --agent-access-level lets those agents’ code do more, so
it asks Proceed? [y/N] first and says what the new level lets them do (--yes skips the question, and is
required without a terminal: the command exits 2 before sending anything; answering no exits 1 and changes
nothing); lowering it asks nothing. See agent access.
# Rename a workspace
afy workspaces update invoice-pipeline --name invoices
# Set a description
afy workspaces update research -d "Retrieval corpus, scrapers, and evaluators"
# Clear it
afy workspaces update research -d ""
# Its agents only read here unless set otherwise
afy workspaces update research --agent-access-level readEverything inside a workspace refers to it by id, so a rename moves nothing: its
agents keep running and are not redeployed, and its collections, secrets and grants
stay where they are. What changes is the name people and code use. Code that
addresses the workspace by its old name (an SDK’s workspace="old-name", a
command’s --workspace old-name) stops finding it. An agent using
workspace="auto" is unaffected, because it reads the workspace’s id. A name
another of your workspaces already uses is refused (409 WORKSPACE_NAME_TAKEN).
Changing the regions an Aetherfy workspace allows
afy workspaces regions <name> --regions ... sets the full set of regions a
workspace owns: the set you name replaces the current one, so it adds the regions
that are new and removes the ones left out. A workspace’s regions are a ceiling on
where its agents and collections may be placed, not a placement: adding a region
copies nothing, and removing one is refused while an agent or a collection of the
workspace still uses it. So the change copies and deletes no data, and asks nothing.
| Flag | Type | Default | Description |
|---|---|---|---|
--regions | strings | none, required | The full set of regions the workspace owns, comma-separated |
--wait | bool | false | Follow the change to its end |
afy workspaces regions research --regions us-east-1,eu-central-1
afy workspaces regions research --regions us-east-1 --wait --json--regions is checked before anything is sent, with the same refusals as
afy workspaces create (see the table above) and exit 2, ending
Nothing was changed.: a name that is not a region, a region your plan does not
open, more regions than the plan allows, an empty value. Each lists the regions
your plan allows. When the control plane itself refuses the change, the message
is followed by every rule it names, one per line, for example:
Error: Request validation failed.
- Your plan allows 1 region(s) per workspace; you asked for 2.The change runs in the background, and afy workspaces info <name> shows the
regions once it finishes. --wait follows it, as afy start --wait follows a
start: exit 0 when it succeeds, 1 when it fails, and 4 when it is still running
after 30 minutes. Asking for the regions the workspace already allows changes
nothing and exits 0. Removing a region still in use is refused with 422
WORKSPACE_NARROW_BLOCKED_BY_RESOURCES; when the control plane names the regions in
use (regions_in_use), the message ends Regions still in use: <r1, r2>.. Re-deploy the agents and change the collections’ regions first
(see /cli/vectors). The refusals are listed on
/agents/api-workspaces.
Under --json the output holds workspace, change (the control plane’s
answer: operation_id, status, current_regions, from_regions,
to_regions, regions_to_add and regions_to_remove) and operation, the
finished operation under --wait, else null.
Deleting an Aetherfy workspace
afy workspaces delete <name> deletes a workspace.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--yes | -y | bool | false | Delete without asking |
Without --yes the Aetherfy CLI asks you to type the workspace name exactly.
Typing anything else cancels: the command exits 1 with Cancelled, deletes
nothing, and under --json writes an error document (code CLI_CANCELLED) on stderr and nothing on
stdout. Without a terminal the command is refused before asking, with exit 2:
This deletes workspace '<name>' and all its secrets; pass --yes to confirm without a prompt.
afy workspaces delete research
afy workspaces delete research --yesAetherfy refuses the deletion while the workspace still holds resources. Both preconditions are checked before anything is removed:
| Precondition | If unmet |
|---|---|
| It is not the account’s only workspace | 409 WORKSPACE_IS_LAST — every account keeps at least one |
| The workspace has no active agents | 409 WORKSPACE_HAS_AGENTS, naming the count — remove or move them first (afy update <agent> --workspace) |
| The workspace has no live vector collections | 409 WORKSPACE_HAS_COLLECTIONS, naming the count — delete or move them first |
Once both hold, deletion removes the workspace record and its workspace-scoped secrets:
| Item | Effect |
|---|---|
| The workspace record | Deleted |
| Workspace-scoped secrets | Deleted with it |
| Vector collections | Never touched — deletion does not cascade to collection data, which is why the workspace must be empty of them first |
The collections precondition is the one that surprises people, because an
empty-looking workspace in the agents view can still be holding collections.
Move them out with afy collections move <name> --workspace <workspace> --to <other>,
or delete them — see /cli/vectors.
Listing the agents in an Aetherfy workspace
afy workspaces agents <workspace> lists a workspace’s agents in two sections. It
takes one positional argument and no flags of its own.
afy workspaces agents research
afy workspaces agents research --jsonLives here is the agents that live in the workspace:
| Column | Meaning |
|---|---|
| Name | The agent name |
| Type | SERVICE or JOB |
| Status | Current lifecycle status |
| Created | Creation timestamp |
Granted access is the agents of your other workspaces that were granted access to this one, with when:
| Column | Meaning |
|---|---|
| Name | The agent name |
| Granted | When the grant was made, in UTC |
A grant gives an agent access to the workspace’s collections; it does not move the
agent (afy update <agent> --workspace <name> moves one, and afy access <agent>
manages its grants). An empty section says so: Lives here: no agents and Granted access: no agents from other workspaces have access to this one.
With --json the output is an object with both lists, always arrays and never null,
so a script reads the same shape for an empty workspace as for a full one:
{
"living": [{"id": "6f1c2b7e-0a2d-4f8e-9c31-2b0d5a7e4411", "name": "reporter", "status": "running"}],
"granted": [{"id": "3b7a9c52-1d4e-4f60-8a2b-9e5c7d1f0a64", "name": "crawler", "granted_at": "2026-10-12T08:15:00Z"}]
}living holds the agents as the workspace’s agent list
returns them (shortened above), granted the granted-agents list. An unknown
workspace is refused with WORKSPACE_NOT_FOUND and a failing exit code.
How Aetherfy agents join and use a workspace
Every Aetherfy agent lives in exactly one workspace, chosen when it is created.
aetherfy.yaml does not name it. To move an agent to another workspace:
afy update catalogue-scraper --workspace researchA move redeploys a live agent into its new workspace; see moving an agent.
Agents that share an Aetherfy workspace can reach each other over HTTP: an agent looks a
peer’s URL up by name when it makes the call (how is on
/platform/workspaces), so a peer created or recreated later is found
without redeploying the caller. The platform’s own environment variables, AETHERFY_PEERS_URL
among them, are why the AETHERFY_ prefix is reserved and cannot be used for your own secret
keys — see /cli/secrets.