Docs
⌘K

Regions

Choose where in the world a sandbox runs.

For your agent

agental.io/docs/regions.md

A region is a part of the world: eu (servers in the European Economic Area or the United Kingdom), us and apac. A sandbox runs in one region, and stays there: it is never placed, moved or kept in another. Only regions that have servers now are offered.

GET/v1/regions
curl -X GET https://agental.io/v1/regions \
  -H "Authorization: Bearer $AGENTAL_API_KEY"
json
{
  "regions": [
    {
      "name": "eu",
      "label": "Europe",
      "about": "Servers in the European Economic Area or the United Kingdom.",
      "default": true,
      "sizesWithRoom": ["tiny", "small", "medium", "large"]
    }
  ]
}
  • default is where a sandbox is made when its create names no region. That is eu.
  • sizesWithRoom is what could be made there now. It changes by the second.

Make a sandbox in a region

curl -X POST https://agental.io/v1/sandboxes \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Idempotency-Key: task-44" \
  -H "Content-Type: application/json" \
  -d '{"name":"agent-1","regions":["eu","us"]}'
  • region names one region. regions names up to three, in the order to try them: the sandbox is made in the first that has room. Send one or the other.
  • Left out, the sandbox is made in eu. main means eu too.
  • A sandbox made from a snapshot is made in the snapshot's region.
  • A region with no servers answers 400 unsupported_region, and the message names the regions there are.

When a region is full

When no server in the region has room right now, a create waits for some before it is refused. It answers 202 with waiting, and nothing is made yet: send the same request again with the same Idempotency-Key every 10 seconds, as the SDKs do, and it is made as soon as there is room. It is waited for until waiting.until, kept from its first try, about two and a half minutes. A create is never moved to another region by itself. When none of the regions it names has room by then, it answers 409 capacity_exceeded, and error.regionsWithRoom lists the other regions that have room for its size now. Send it again to one of them with a new Idempotency-Key, or wait and try again.

json
{
  "waiting": {
    "region": "eu",
    "askedAt": "2026-11-05T12:00:00.000Z",
    "until": "2026-11-05T12:02:30.000Z"
  }
}

Above, what a create that waits for room answers. Below, what one answers when its wait is over and there is still none.

json
{
  "error": {
    "code": "capacity_exceeded",
    "message": "Every server in region eu is too busy to take another sandbox right now. Try again later. Region us has room for one now: send region us, with a new Idempotency-Key.",
    "regionsWithRoom": ["us"]
  }
}

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]