> ## Documentation Index > Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt > Use this file to discover all available pages before exploring further. # Regions > Run machines in Frankfurt or New York. Pick the region per machine, with one login, one bill and the same secrets in both. boxd runs in two regions, and every org can use both. Every machine lives in one of them, the one it was created in, and has its URL, address and SSH port there. Everything around your machines works in both regions with the same login: your account, your orgs and their members, API keys, env vars and secrets, integrations, and billing. | Region | Machine URLs | | - | - | | **Frankfurt** (`fra`) | `.boxd.sh` | | **New York** (`nyc`) | `.nyc.boxd.sh` | Put machines close to the people and services they talk to. A machine in New York answers users in the US without a round trip across the Atlantic. The [status page](https://status-boxd.com) shows each region's uptime and incidents. > [!NOTE] > > Regions need CLI 0.3.0 and SDK 0.3.0 or later. Older versions keep working in Frankfurt. Re-run the [installer](https://docs.boxd.sh/cli/installation.md#upgrade) to upgrade the CLI. ## Create a machine in a region > [tab] CLI > > ```bash theme={"theme":"github-dark"} > boxd machine new web --region nyc > ``` > > ```text theme={"theme":"github-dark"} > Connect: > ssh ssh web.nyc.boxd > cli boxd machine connect web.nyc > browser https://web.nyc.boxd.sh > ``` > [tab] Console > > The **New machine** dialog has a **Region** field. It starts on the org's default region, else the closest one. > [tab] TypeScript > > ```typescript theme={"theme":"github-dark"} > const machine = await boxd.machines.create({ name: "web", region: "nyc" }); > machine.region; // "nyc" > ``` > [tab] Python > > ```python theme={"theme":"github-dark"} > machine = boxd.machines.create("web", region="nyc") > machine.region # "nyc" > ``` The machine's addresses all sit under its region's zone: `https://web.nyc.boxd.sh`, [subdomain proxies](https://docs.boxd.sh/guides/proxies.md) such as `https://api.web.nyc.boxd.sh`, and [raw port forwards](https://docs.boxd.sh/guides/port-forwarding.md) on `web.nyc.boxd.sh`. Disks take `--region` the same way (`boxd disks new data --size 10G --region nyc`), and a snapshot is saved in its machine's region. Machine names are unique within a region, so `web` can exist in Frankfurt and in New York at the same time. A region's ID, such as `nyc`, can't be a machine name. ## Which region a command uses When a command names no region, each surface picks one in this order: | Surface | Order | | - | - | | CLI | `--region`, then `BOXD_REGION`, then `boxd config set region`, then the org's default region, then the closest region | | Console | The org's default region, then the closest region | | SDKs | The call's `region`, then the client's (`new Boxd({ region })` or `BOXD_REGION`), then Frankfurt | So out of the box, the CLI and the console put a new machine in the region closest to you, until the org sets a default region. The CLI finds the closest region by timing a connection to each region, once a day. The SDKs go only where you point them, so a script runs in the same region wherever it starts. ### Set the org's default region The default region is where new machines and disks go when nobody names one. Org owners and admins set it. > [tab] CLI > > ```bash theme={"theme":"github-dark"} > boxd manage regions default nyc # new machines and disks go to New York > boxd manage regions default none # back to the closest region > ``` > [tab] Console > > Under **Settings** > **General** > **Regions**, pick a **Default region**. **Closest region** clears it. > [tab] TypeScript > > ```typescript theme={"theme":"github-dark"} > await boxd.orgs.setDefaultRegion("nyc"); > await boxd.orgs.clearDefaultRegion(); > ``` > [tab] Python > > ```python theme={"theme":"github-dark"} > boxd.orgs.set_default_region("nyc") > boxd.orgs.clear_default_region() > ``` The CLI and the console follow it. The SDKs read it with `orgs.getDefaultRegion()` (`get_default_region()` in Python) and leave the choice to you. ### Set your own default ```bash theme={"theme":"github-dark"} boxd config set region nyc # this laptop, until you change it export BOXD_REGION=nyc # this shell, for the CLI and the SDKs ``` ## Work across regions ### Add the region to a name A machine, snapshot or disk name that ends in a region ID names it in that region, for one command. `web.nyc` is the machine `web` in New York: ```bash theme={"theme":"github-dark"} boxd machine exec web.nyc -- uptime boxd machine connect web.nyc boxd machine cp ./build.tar web.nyc:/home/boxd/ boxd machine new web2 --from-snapshot base.nyc # created in New York, where the snapshot is ``` Plain `web` is the machine in the region the command runs in. A suffix and a `--region` that name different regions fail, and so does a command that names things in two regions. ### List every region A list shows one region and counts what the org has in the others: ```text theme={"theme":"github-dark"} and 3 in nyc (add `--region all` to list them) ``` `--region all` lists every region in one table, with a REGION column. With `--json`, it prints one array, and each row carries its `region`. It works with `machine list`, `snapshots list`, `disks list`, `teams list` and `manage domain get`. Every other command acts in one region. ### Find a name in another region When the region a command runs in doesn't have the name, the CLI looks in the others and prints the command to run there: ```text theme={"theme":"github-dark"} $ boxd machine exec web -- uptime no machine "web" in fra There is a machine "web" in nyc: boxd machine exec web --region nyc -- uptime ``` A name one or two letters off gets a `Did you mean` line instead. The [SDKs](#from-the-sdks) put the same answer on their errors. ### SSH The CLI's [SSH config](https://docs.boxd.sh/cli/commands.md#editor-and-ssh-integration) lists machines in other regions as `..boxd`, each with its region's address, port and host key. Machines in Frankfurt stay `.boxd`. ```bash theme={"theme":"github-dark"} ssh web.nyc.boxd code --remote ssh-remote+web.nyc.boxd /home/boxd ``` ## What stays in a region A machine stays in the region it was created in, and what you make from it stays there too: * **Forks.** A fork is created in its source machine's region. * **Snapshots.** A snapshot lives in its machine's region, and machines created from it start there. * **Disks.** A disk attaches to machines in its own region. * **Checkpoints and backups.** They're stored with the machine, in its region. * **Private networking.** `.boxd` and [networks](https://docs.boxd.sh/guides/vm-to-vm.md#networks) reach machines in the same region. Between regions, use the machine's HTTPS URL, a [raw port forward](https://docs.boxd.sh/guides/port-forwarding.md), or your own WireGuard or Tailscale. * **Team default snapshots.** A team is the same in every region, with a default snapshot of its own in each. Set New York's with `boxd teams set-default-snapshot backend base.nyc`. * **The org's wildcard domain.** Each region has its own. See [Domains](#domains). To start the same setup in another region, create a machine there and copy what it needs with `boxd machine cp`, through your laptop. ## What every region shares These are the same in every region your org uses: * Your account, your CLI login and your API keys * The org, its members, roles and teams * [Env vars and secrets](https://docs.boxd.sh/guides/env-secrets.md) * [Integrations](https://docs.boxd.sh/guides/integrations/connections.md) and agent logins, such as Claude Code, Codex and Git * Billing, credits and usage, at the same rates in every region * The org's defaults for new machines, such as the default size and backup schedule The [machine limit](https://docs.boxd.sh/guides/resources.md#organization-limits) is set once and counts each region on its own. An org with a limit of 100 can have 100 machines in Frankfurt and another 100 in New York. `boxd manage machine-limit` shows how many are in use in each region. ## Domains Per-machine [custom domains](https://docs.boxd.sh/guides/custom-domains.md#per-machine) point at the machine's region. `boxd machine domain add` prints the right records, such as a wildcard CNAME to `web.nyc.boxd.sh` for a machine in New York. An org has one [wildcard domain](https://docs.boxd.sh/guides/custom-domains.md#org-wide-wildcard-domain) in each region. Each covers the org's machines in its region and is delegated to that region's nameservers. One region's domain can't be the same as, inside, or around another's, so give them names side by side: ```bash theme={"theme":"github-dark"} boxd manage domain set preview.mysaas.com --region fra # NS records to ns1.boxd.sh and ns2.boxd.sh boxd manage domain set preview-nyc.mysaas.com --region nyc # NS records to ns1.nyc.boxd.sh and ns2.nyc.boxd.sh boxd manage domain get --region all # every region's domain ``` Name the region when you set a domain. Without `--region`, the command acts in the region the CLI picks, as above. In the console, the wildcard domain setting asks which region a new domain is for. ## Tailscale and NetBird An org's [Tailscale](https://docs.boxd.sh/guides/tailscale.md) or [NetBird](https://docs.boxd.sh/guides/netbird.md) network covers the regions the boxd team sets it up in, by default every region the org had at that moment. A network set up before New York existed covers Frankfurt only. In a region the network doesn't cover, the org's machines stay on the public internet, and creating one there is refused. To add New York to your network, ask the boxd team and send a new key with the request. ## Inside a machine `boxd info` shows the machine's region, and the in-machine `boxd` acts in that region: * Lists show the machines and snapshots in this region, with a count of the rest. * A name that's in another region gets an error with the command to run from your laptop. * `--region` naming another region is refused. Work across regions from the CLI on your laptop or from an SDK. ## From the SDKs Pass `region` to the client, or to any call on a machine, snapshot or disk. Calls on the account, the org, API keys, env vars and billing work the same whatever `region` says. ```typescript TypeScript theme={"theme":"github-dark"} import { Boxd } from "@boxd-sh/sdk"; const nyc = new Boxd({ region: "nyc" }); // machines, snapshots and disks in New York await nyc.machines.create({ name: "web" }); await nyc.machines.exec("web", { command: "uptime" }); const boxd = new Boxd(); // Frankfurt await boxd.machines.get("web", { region: "nyc" }); // one call in New York const all = await boxd.machines.list({ region: "all" }); all.map((m) => `${m.name} ${m.region}`); ``` ```python Python theme={"theme":"github-dark"} from boxd import Boxd nyc = Boxd(region="nyc") # machines, snapshots and disks in New York nyc.machines.create("web") nyc.machines.exec("web", "uptime") boxd = Boxd() # Frankfurt boxd.machines.get("web", region="nyc") # one call in New York for m in boxd.machines.list(region="all"): print(m.name, m.region) ``` * **Where each thing lives.** Machines, snapshots, disks and org domains carry their `region`. * **Lists.** A list of one region has `elsewhere`, the count in each other region. A `region: "all"` list has `unavailable`, the regions that didn't answer. * **Not found.** A machine, snapshot or disk name that's in another region throws `NotFoundError` with `elsewhere` (the same name in other regions) and `close` (names one or two letters off), and its message says which `region` to pass. See the [TypeScript](https://docs.boxd.sh/reference/typescript-sdk.md#regions) and [Python](https://docs.boxd.sh/reference/python-sdk.md#regions) references. ## From the gRPC API Each region has its own API endpoint. `ListRegions` on `boxd.sh:9443` returns them, each with its `id`, `name`, `zone` and `api_endpoint`. Send calls on machines, snapshots and disks to the region's endpoint, `nyc.boxd.sh:9443` for New York, with the same bearer token or API key. Account, org, API key, env var and billing calls go to `boxd.sh:9443`. See [Regions](https://docs.boxd.sh/reference/grpc-api.md#regions) in the gRPC reference. ## In the console The console at [app.boxd.sh](https://app.boxd.sh) shows every region your org uses: * **Machines**, **Snapshots**, **Disks** and **Domains** have a region filter in the toolbar, set to **All regions** or one region. It starts on your last pick, else the org's default region, else the closest region. * Every machine, snapshot, disk and domain carries a region tag, such as `NYC`. * **New machine** and **New disk** have a **Region** field. * **Settings** > **General** > **Regions** sets the org's default region. ## Where your data lives A machine's disk, memory, snapshots, checkpoints and backups are stored in its region. Your account and org data, such as members, API keys, secrets and integrations, are kept in every region your org uses, so machines there get them. A Tailscale or NetBird key is kept only in the regions its network covers. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.