Regions and failover
Let the agent select a region, or restrict it to a list you choose.
The agent chooses a primary region and keeps other reachable regions available for failover.
Automatic region selection
Leave upstreams unset to use automatic selection. The agent follows the available regions and favors low round-trip time. See Endpoints for regional addresses.
Pinned regions
Set upstreams only if you want to restrict which regions the agent can use:
upstreams = ["fra.sol.zerocopy.sh:443", "ams.sol.zerocopy.sh:443"]Keep this top-level key above [listen] and [log], then restart the agent. Each entry must be a regional host under sol.zerocopy.sh with a port. Use regional host names, not IP addresses or the anycast name sol.zerocopy.sh.
Pinning also restricts failover: the agent will not use an unlisted region if all listed regions are unavailable.
Region changes
The agent checks reachable regions and changes its choice when a better connection is available or the current connection fails. Small latency differences may not cause a switch. You do not need to restart it for ordinary failover.
If it consistently selects an unexpected region, check your pinned list, DNS and outbound UDP access from the agent's host. Contact support with the logs if the problem persists.
Failover
If a region connection closes during a request, the agent may send the same request through another region. The first region may already have forwarded it. Treat delivery as potentially duplicated, and check the transaction's signature before sending a replacement.
When a request needs a region and none is available, it can return not_ready with waiting_for: "upstream". Check network access and the service log. See Confirmation and retries for handling uncertain outcomes.
Connection limits
A region allows up to 32 QUIC connections per API key. Agents and direct QUIC clients using the same key share that limit. Reuse running agents and client connections rather than creating a new process or connection for each send.