Regions and replication in Aetherfy
The regions Aetherfy runs in
Aetherfy operates in three regions. These exact codes are what the Aetherfy API,
the Aetherfy SDKs and aetherfy.yaml accept — no other spelling is valid.
| Code | Location |
|---|---|
us-east-1 | US East (Virginia) |
eu-central-1 | EU Central (Frankfurt) |
ap-southeast-1 | Asia Pacific (Singapore) |
us-east-1 is the canonical default. Wherever a region is optional and you omit
it, Aetherfy resolves to us-east-1 unless your workspace or resource says
otherwise.
How your plan scopes regions in Aetherfy
This is the rule that governs everything else on this page: how many regions a workspace may own is a property of your Aetherfy plan.
| Plan | Regions per workspace |
|---|---|
| Free | 1 |
| Starter | 1 |
| Performance | up to 3 |
| Enterprise | unlimited (of the regions above) |
Multi-region replication in Aetherfy begins at the plan literally named Performance. On Free and Starter a workspace has exactly one region, so there is nothing to replicate to.
A workspace owns its regions in Aetherfy
Every workspace owns its regions: at least one, and at most your plan’s limit. You
choose them when you create the workspace, and you change them later with the
regions operation, which sets the workspace’s full set of regions: the ones you name
are added, the ones you leave out are removed. There is no account-wide region rule: a
Free or Starter account may have one workspace in us-east-1 and another in eu-central-1. On Performance and above,
multi-region is one workspace spanning several regions.
A workspace’s regions are a ceiling, not a placement:
- A collection takes its workspace’s regions, or a subset you name when you create
it. A region outside the workspace’s is refused with 422
COLLECTION_REGIONS_NOT_IN_SCOPE. - An agent deploys into a region of its workspace.
- Adding a region to a workspace copies nothing. Removing one is refused (422
WORKSPACE_NARROW_BLOCKED_BY_RESOURCES) while an agent or a collection of the workspace still uses it.
The control plane’s API is at agents.aetherfy.com:
PATCH /api/v1/workspaces/{workspace}/regions sets a
workspace’s regions, authenticated with the same afy_live_ key as everything else.
It changes no data, and an empty list is refused (422 WORKSPACE_REGIONS_EMPTY).
A change that has to move data runs asynchronously and returns an operation you
poll with GET /api/v1/operations/{operation_id} rather
than blocking until it is done.
Moving a single collection between Aetherfy workspaces, or setting its regions
directly, is
PATCH /api/v1/collections/{collection_id}. A move
keeps the collection’s regions and moves no data, so it is refused unless each of
them is one of the target workspace’s regions. A move also takes the collection’s
aliases with it, and is refused before anything starts if its name or one of its
aliases is already taken in the target workspace. Adding a region to a collection
copies its data, and your plan limits how many such changes, and how much data, in a
rolling 30 days (limits). The full
control-plane reference is at
the Agent REST API.
Per-resource regions in Aetherfy
There is no account-level region in Aetherfy: regions belong to a workspace. Within its workspace’s regions, a collection carries its own region list and an agent deployment carries its own. Two collections in the same Aetherfy account can legitimately live in different regions.
When you omit regions: from aetherfy.yaml, Aetherfy picks defaults bounded by
your plan rather than failing. See the aetherfy.yaml reference for the field itself.
How Aetherfy replicates writes across regions
Replication in Aetherfy is asynchronous. A write lands in the region that served the request and then fans out to the other regions that the collection itself is placed in. A collection placed in a subset of your allowed regions never fans out beyond that subset — the collection’s own placement is the boundary, not the plan maximum and not the workspace.
The properties Aetherfy guarantees on that path:
| Property | Behaviour |
|---|---|
| Ordering | Changes to one collection are queued and applied in the order they were made. In a collection placed in several of your regions, a point deleted in one region stays deleted in every region, including when an earlier write of it is applied late: Aetherfy compares each point’s write record with its delete record and removes a stale copy within hours. In your regions a schema or index change applied late never overrides a newer one: each carries a write record, and an older one is ignored, and a region that missed an index change is brought to the newest state within hours |
| Delivery | At-least-once |
| Operations | Idempotent, so a redelivery is harmless |
| Region outage | Changes queue and are applied when the region returns |
Because the fan-out is asynchronous, a read issued in another region immediately after a write may not see it yet. Aetherfy does not offer a synchronous cross-region write.
Adding a region to an Aetherfy collection that already has data
Adding a region to a collection that already holds vectors triggers a backfill. The backfill runs asynchronously in batches, so the new Aetherfy region becomes complete over time rather than at the moment you change the configuration.
Removing a region from an Aetherfy collection
Removing a region from a collection (on Performance and above, where a collection can
live in more than one region) is a region change, made the same way as adding one: from
the dashboard, with afy or with
PATCH /api/v1/collections/{collection_id}. It runs as an
operation you poll, in this order:
- The collection stops living in the removed region. From then on no write is replicated to it, and a request that reaches that region for the collection is forwarded to a region that still holds it.
- Writes the removed region accepted before that point are still being replicated. The operation waits until every one of them has been applied in the regions the collection keeps.
- Only then is the removed region’s copy deleted. The region’s daily backups of the collection, kept in a storage bucket in that region, are not deleted with it: they expire on the bucket’s 7-day lifecycle, like every daily backup.
Writes keep working throughout, wherever you send them. On Performance and above, a
write accepted in any of your regions is replicated to each region the collection keeps
before the removed region’s copy is deleted. The operation completes then: no sooner than
about seven minutes after step 1, the longest a write accepted just before it can still
take to be sent. If the removed region’s replication cannot be confirmed within an hour, the
operation completes anyway, because your change has already taken effect: the collection
lives only in the regions you asked for. The removed region’s copy is then deleted later,
once its replication has been applied. So a removal can still show as running, and
afy collections regions <name> --wait can give up after 30 minutes saying it still runs, while
the collection already serves only from the regions it keeps: what is still running is
the clean-up of the removed region’s copy.
Deleting an Aetherfy collection deletes it in all of its regions
A collection is one collection, whichever regions it lives in. Deleting it deletes it in all of them at once: there is no delete of a single region’s copy. The only way to take a collection out of one region is to remove that region from it, above. A write sent in the first minute after a delete, to a region that has not yet heard of it, can be accepted. It is not replicated: if it reached the collection’s first region, where its backup is taken, a restore brings it back; in any other region it is removed with the collection. See recovering a deleted collection.
What widening and narrowing regions does in Aetherfy
Widening a workspace’s regions in Aetherfy is data-neutral:
- Existing collections keep their explicit regions and do not auto-replicate into the newly-allowed region.
- Agents keep their deployment regions and do not auto-redeploy. Getting an agent into a newly-allowed region requires a redeploy.
Narrowing never silently deletes data. Aetherfy blocks the change until you have migrated the affected resources yourself.
The Aetherfy billing consequence of removing a region
This one surprises people, so it is worth stating flatly: removing a region from
aetherfy.yaml is a compute-only change in Aetherfy. The machines in that
region come down, but your vector data stays there, and the replica keeps being
billed until you explicitly release it. Dropping a region from your deployment
configuration is not the same act as deleting the data in it.
Billing behaviour for regions is covered in full at Billing and spend caps.
How Aetherfy agents reach the vector database
An Aetherfy agent reaches the vector database inside its own region. There is no cross-region hop on that path, which is why an agent’s deployment region and the regions of the collections it reads are worth keeping aligned.