Multi-region

Regions and zones

A region is a geographic location with its own control-plane cell, data plane, storage and egress. A zone is an independent failure domain inside a region — separate power, network and racks.

Tier 4 needs desktop-class hardware at 1:1 oversubscription, so it is only in regions where that capacity is justified. A tier 4 create in a region without it fails with tier_unavailable_in_region rather than silently placing elsewhere, because silent placement would violate residency.

What is global and what is regional

Global state lives in a single-primary Postgres replicated to every cell. Writes are rare and latency-tolerant; reads are served locally.

Routing

api.workspaces.build          anycast -> nearest healthy control cell
                              a call about an existing session is forwarded
                              to that session's region, transparently

connect.workspaces.build      resolves to the session's region directly;
                              streams never cross regions

*.run.workspaces.build        resolves to the session's region's edge-router

A control call about a session in another region is forwarded, not rejected. The caller sees one API and does not have to know where its session lives. Data calls are never forwarded — a stream that crossed regions would add tens of milliseconds to every frame, so the gateway hostname resolves regionally from the start.

Choosing a region

In precedence order:

1. Residency policy. If the organization or project is pinned, that is the only answer. A request for another region is refused.
2. Explicit region on the request.
3. Volume or snapshot locality. Restoring a snapshot places in that snapshot's region.
4. Project default region.
5. Lowest-latency region from the caller, measured at the edge.

Residency

{
  "residency": {
    "mode": "pinned",
    "regions": ["fra1"],
    "applies_to": ["sessions", "volumes", "snapshots", "recordings", "logs"],
    "allow_cross_region_copy": false
  }
}

Enforcement is at four layers, because one of them being misconfigured must not be enough:

• admission refuses a create in a disallowed region.
• placer filters disallowed regions out of candidates before scoring.
• The storage layer refuses to materialise a volume, snapshot or recording outside the allowed set.
• billing and the usage API keep aggregates regional when the policy says so.

Metadata — the fact that a session exists, its ID, its state, its usage totals — is global, because billing and the API are global. Content never is. This distinction is in the data processing agreement explicitly, because it is the question every regulated customer asks.

Failure behaviour

Building a multi-region integration

const REGIONS = ['bom1', 'iad1', 'fra1']

async function createResilient(spec: SessionSpec) {
  const ordered = [spec.region ?? defaultRegionFor(spec), ...REGIONS].filter(unique)
  for (const region of ordered) {
    try {
      return await wb.sessions.create({ ...spec, region })
    } catch (e) {
      // retry the next region only for capacity, never for quota or policy
      if (e.code !== 'capacity_unavailable') throw e
    }
  }
  throw new Error('no region had capacity')
}

Retry only on capacity_unavailable. Retrying a quota_exceeded across regions does nothing — quotas are per organization, not per region — and retrying a residency refusal would be an attempt to defeat a control the customer asked for.

Latency between regions

Round-trip times used when planning cross-region work:

If an agent loop is chatty against a session, the client should run in the session's region. Cross-region exec adds a full round trip to every call, which an agent making hundreds of calls will feel far more than the session's start latency.