Regions & Discovery

Ngris runs tunnel-servers in multiple regions so traffic enters the network as close to your users as possible. Endpoints are region-less — region is a property of the serving agent / tunnel, not of the endpoint. Where traffic for an endpoint ingresses is decided by which region the agent connects to, which is chosen at agent start-up by discovery.

Available regions:

eu-north-1 — Helsinki, Finland
us-east-va — Ashburn, Virginia

More regions coming — check GET /v1/agent/discover for the live list.

When the agent starts it asks the discovery service which tunnel-server to dial. Discovery decides based on (in order):

Operator preference (--region). Force a specific region for testing, latency comparisons, or pinning.
GeoIP of the agent. No --region? Discovery looks at your source IP and routes to the nearest healthy region.
Default region. If all else fails, you land on the closest discovery POP (currently eu-north-1).

The endpoint itself carries no region, so passing --url mysite.example.com does not pin you to a region — the same hostname can be served from whichever region its agent connected to.

Inspect the discovery response

# What region am I routed to right now?
curl -s https://connect.ngris.com/v1/agent/discover | jq

# Force a specific region
curl -s 'https://connect.ngris.com/v1/agent/discover?region=us-east-va' | jq

Example response

{
  "region": "us-east-va",
  "tunnel_server": "5.161.61.173:1024",
  "fallbacks": ["65.21.194.241:1024"],
  "ttl_seconds": 60
}

Where an endpoint is served from

Creating an endpoint does not pick a region — endpoints are region-less. The serving region is chosen by the agent when it connects (see discovery and the --region flag below). The same endpoint can be served from eu-north-1 today and us-east-va tomorrow simply by running its agent against a different region.

Connect your agent in the region close to your users, not close to the agent host. A US user hitting mysite.example.com served through an EU region pays the EU-US round-trip per request. Connecting the agent to us-east-va moves traffic ingress to Ashburn, where TLS terminates and the request enters the tunnel.

The agent itself can be anywhere — on your laptop, in a home server, in a different cloud. It dials out to its region's tunnel-server, so the agent's geography only affects how far the data has to travel through the tunnel, not the public-facing latency for users.

Where does my traffic go?

User in NYC
    │ HTTPS
    ▼
Cloudflare → us-east-va tunnel-server (Ashburn)
    │ TLS terminates here
    │ tunnel → agent (anywhere on the internet)
    ▼
Your origin app (localhost:8080)

Agent flags & environment variables

Two ways to control where the agent connects, in order of precedence:

Signal	Wins when	Example
`--region <slug>` env: `NGRIS_AGENT_REGION`	Explicitly set. Forces a specific region.	`ngris http 3000 --region us-east-va`
(none)	Falls back to GeoIP of your source IP → nearest healthy region.	`ngris http 3000`

The endpoint hostname does not influence the region. Endpoints are region-less, so --url selects which endpoint the agent serves but never which region it connects to — region comes from --region or GeoIP alone.

Region selection examples

# 1) GeoIP-routed (no flags) — easiest, recommended for most users
ngris http 8080

# 2) Serve a specific endpoint (region still GeoIP / --region, not the endpoint)
ngris http 8080 --url mysite.example.com

# 3) Force a region (testing, comparisons, pinning)
ngris http 8080 --region us-east-va

# Or via env var
NGRIS_AGENT_REGION=us-east-va ngris http 8080

Fallbacks & failover

The discovery response includes a list of fallback tunnel-servers in other healthy regions. If your primary tunnel-server becomes unreachable, the agent automatically cycles through fallbacks before re-querying discovery.

You don't need to handle this in your code. The agent transparently reconnects through a fallback within a few seconds. Existing in-flight HTTP requests are returned with a brief retry; new requests just route to the fallback.

A region is excluded from discovery responses when:

Its tunnel-server hasn't heartbeated for >30s
It's marked draining by ops (planned maintenance)
It's been failed over within the cooldown window

Health-aware discovery response

{
  "region": "us-east-va",
  "tunnel_server": "5.161.61.173:1024",
  "fallbacks": [
    "65.21.194.241:1024"
  ],
  "ttl_seconds": 60,
  "advisory": ""
}

Verbose agent output

Discovery: region=us-east-va tunnel_server=5.161.61.173:1024 fallbacks=[65.21.194.241:1024]
Connected to tunnel-server: 5.161.61.173:1024
Endpoint URL: https://mysite.example.com