Regions

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`)	`<machine>.boxd.sh`
New York (`nyc`)	`<machine>.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 shows each region’s uptime and incidents.

Regions need CLI 0.3.0 and SDK 0.3.0 or later. Older versions keep working in Frankfurt. Re-run the installer to upgrade the CLI.

Create a machine in a region

CLI
Console
TypeScript
Python

boxd machine new web --region nyc

Connect:
  ssh       ssh web.nyc.boxd
  cli       boxd machine connect web.nyc
  browser   https://web.nyc.boxd.sh

const machine = await boxd.machines.create({ name: "web", region: "nyc" });
machine.region; // "nyc"

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 such as https://api.web.nyc.boxd.sh, and raw port forwards 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.

CLI
Console
TypeScript
Python

boxd manage regions default nyc      # new machines and disks go to New York
boxd manage regions default none     # back to the closest region

await boxd.orgs.setDefaultRegion("nyc");
await boxd.orgs.clearDefaultRegion();

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

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:

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:

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:

$ 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 put the same answer on their errors.

SSH

The CLI’s SSH config lists machines in other regions as <machine>.<region>.boxd, each with its region’s address, port and host key. Machines in Frankfurt stay <machine>.boxd.

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. <machine>.boxd and networks reach machines in the same region. Between regions, use the machine’s HTTPS URL, a raw port forward, 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.

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
Integrations 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 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 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 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:

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 or NetBird 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.

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}`);

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 and Python 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 in the gRPC reference.

In the console

The console at 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.

Getting started

Guides

Integrations and automations

Use cases

References

Create a machine in a region

Which region a command uses

Set the org’s default region

Set your own default

Work across regions

Add the region to a name

List every region

Find a name in another region

SSH

What stays in a region

What every region shares

Domains

Tailscale and NetBird

Inside a machine

From the SDKs

From the gRPC API

In the console

Where your data lives

​Create a machine in a region

​Which region a command uses

​Set the org’s default region

​Set your own default

​Work across regions

​Add the region to a name

​List every region

​Find a name in another region

​SSH

​What stays in a region

​What every region shares

​Domains

​Tailscale and NetBird

​Inside a machine

​From the SDKs

​From the gRPC API

​In the console

​Where your data lives

Create a machine in a region

Which region a command uses

Set the org’s default region

Set your own default

Work across regions

Add the region to a name

List every region

Find a name in another region

SSH

What stays in a region

What every region shares

Domains

Tailscale and NetBird

Inside a machine

From the SDKs

From the gRPC API

In the console

Where your data lives