Skip to Content
CLIafy workspaces
Raw

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.

SubcommandPurpose
afy workspaces create <name> --regions <r1[,r2]>Create a workspace, with the regions it owns
afy workspaces listList 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.

FlagShortTypeDefaultDescription
--regionsstringsasked on a terminalThe regions the workspace owns: 1 up to your plan’s limit, from the regions your plan allows. Repeat the flag or comma-separate
--description-dstringemptyWorkspace 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.:

RefusalMessage
A region is not open on your planregion <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:

RuleDetail
Length3–63 characters
Character setLowercase alphanumeric and hyphens
BoundariesCannot 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
ColumnMeaning
NameThe workspace name
AgentsNumber of agents assigned to it
DescriptionThe description, if set
CreatedCreation 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 --json

Fields 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.

FlagShortTypeDefaultDescription
--namestringemptyRename the workspace
--description-dstringemptyWorkspace description (optional)
--agent-access-levelstringnoneThe 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-yboolfalseRaise 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 read

Everything 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.

FlagTypeDefaultDescription
--regionsstringsnone, requiredThe full set of regions the workspace owns, comma-separated
--waitboolfalseFollow 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.

FlagShortTypeDefaultDescription
--yes-yboolfalseDelete 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 --yes

Aetherfy refuses the deletion while the workspace still holds resources. Both preconditions are checked before anything is removed:

PreconditionIf unmet
It is not the account’s only workspace409 WORKSPACE_IS_LAST — every account keeps at least one
The workspace has no active agents409 WORKSPACE_HAS_AGENTS, naming the count — remove or move them first (afy update <agent> --workspace)
The workspace has no live vector collections409 WORKSPACE_HAS_COLLECTIONS, naming the count — delete or move them first

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

ItemEffect
The workspace recordDeleted
Workspace-scoped secretsDeleted with it
Vector collectionsNever 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 --json

Lives here is the agents that live in the workspace:

ColumnMeaning
NameThe agent name
TypeSERVICE or JOB
StatusCurrent lifecycle status
CreatedCreation timestamp

Granted access is the agents of your other workspaces that were granted access to this one, with when:

ColumnMeaning
NameThe agent name
GrantedWhen 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 research

A 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.

Last updated on