Skip to Content
PlatformRegions & replication
Raw

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.

CodeLocation
us-east-1US East (Virginia)
eu-central-1EU Central (Frankfurt)
ap-southeast-1Asia 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.

PlanRegions per workspace
Free1
Starter1
Performanceup to 3
Enterpriseunlimited (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:

PropertyBehaviour
OrderingChanges 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
DeliveryAt-least-once
OperationsIdempotent, so a redelivery is harmless
Region outageChanges 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:

  1. 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.
  2. 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.
  3. 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.

Last updated on