Regions
Geographic locations where sandboxes run.
Every Daytona sandbox runs in a region: a geographic or logical grouping of compute infrastructure. When creating a sandbox, you can target a specific region, and Daytona schedules the workload on available capacity within that region.
Daytona organizes regions in a four-level placement hierarchy:
| Level | Description |
|---|---|
| Global | The root, with ID: earth. |
| Geo | Groups of macro regions that do not impose a geographic constraint. |
| Macro | One macro region per workload cell; every macro region belongs to one geo group. |
| Edge | The regions where runners place sandboxes; belongs to one macro region. |
Every ID in the hierarchy is a valid region selector. A broad selector (global, geo, or macro) lets Daytona choose an edge region beneath it; an edge region with automatic placement disabled is excluded from broad selection but stays reachable by its exact ID while it is active and routable. Hierarchy counts describe inventory, not capacity: a selectable node can still refuse a create request due to sandbox class constraints, artifact locality, or admission checks.
Shared regions
Regions managed by Daytona and available to all organizations:
| Region | Target | Level |
|---|---|---|
| Earth | earth | Global |
| United States | us | Geo |
| Europe | eu | Geo |
from daytona import Daytona
daytona = Daytona()
# Create a sandbox in the US region
sandbox = daytona.v2.create(region="us")Dedicated regions
Dedicated regions are managed by Daytona and provisioned exclusively for an organization. The infrastructure is not shared with other organizations.
Custom regions
Custom regions run on compute that your organization provides. Daytona provisions the region and you enroll your own runner nodes through bring your own compute (BYOC) to control data locality, compliance, and infrastructure configuration, and scale capacity independently.
Operations
Get region hierarchy
Get the region hierarchy. One response carries every level, from the global root down to edge regions, as a flat list of nodes; each node names its parent, so a client rebuilds the tree from the list. The response includes shared regions and the regions dedicated to your organization; regions dedicated to other organizations are not listed.
curl 'https://api.daytona.com/region-hierarchy' \
--header 'Authorization: Bearer YOUR_API_KEY'The response contains nodes, the hierarchy nodes, and schema_version, which changes with the node contract so a client can reject unsupported versions.
| Field | Description |
|---|---|
id | Node ID. Valid as a region selector. |
name | Display name. |
level | global, geo, macro, or edge. |
parent_id | ID of the immediate parent. null for the Global root. |
child_count | Number of immediate children in this response. |
local_region_count | Number of Edge descendants, including disabled ones and ones excluded from broad placement. Always 1 on an Edge node. null when the API that answered cannot count Edge regions. |
eligible_local_region_count | Number of Edge descendants a broad selector may place in: active, routable, and opted into broad placement. null when the API that answered cannot count Edge regions. |
selectable | On a Global, Geo, or Macro node: whether the API that answered may itself place in at least one descendant. On an Edge node: whether the region is active and routable. |
cell_id | Macro nodes only. The workload cell this macro region represents. |
macro_region_id | Edge nodes only. ID of the parent macro region. |
status | Edge nodes only. Catalog status: active or disabled. |
auto_placement_enabled | Edge nodes only. Whether broad placement may select this region. |
List macro regions
List macro regions. Each macro region is the selector for one workload cell. The list includes shared macro regions and the macro regions dedicated to your organization.
curl 'https://api.daytona.com/macro-regions' \
--header 'Authorization: Bearer YOUR_API_KEY'The response is an array of macro regions:
| Field | Description |
|---|---|
id | Macro region ID. Immutable. Valid as a region selector. |
name | Display name. |
cell_id | Stable identity of the workload cell this macro region represents. Immutable. |
global_region_id | ID of the parent Geo group. Never earth. |
eligible_local_region_count | Number of Edge regions beneath this macro region that a broad selector may place in: active, routable, and opted into broad placement. null when the API that answered cannot count Edge regions. |
selectable | Whether the API that answered serves at least one eligible Edge region of this macro region. |
Get region catalog
Get the macro regions available to you, grouped by Geo group. The catalog is the compact form of the macro region list for clients that only need to know which regions exist and how they nest. It describes topology, not capacity or health: a listed macro region can still refuse a create it has no capacity or matching hardware for. Macro regions dedicated to other organizations are not listed.
curl 'https://api.daytona.com/region-catalog' \
--header 'Authorization: Bearer YOUR_API_KEY'{
"global": {
"eu": ["eu-central"],
"us": ["us-east", "us-west"]
}
}The response has the following fields:
| Field | Description |
|---|---|
global | Holds the Global root. Its keys are Geo group IDs. Each value is the sorted list of the macro region IDs of that group. Each macro region ID is a valid region selector at create time. Geo groups with no macro region you can target are omitted. An empty platform returns 200 with an empty global object. |
List regions
List regions. The list contains edge regions that are active and routable, from shared macro regions and from the macro regions dedicated to your organization. A region that is not routable stays valid for placement but is left out of this list.
# Regions available to the current project
daytona region list