Region & runtimeDomain Configuration Guide

**Recommended:** Use official Lovrabet services: configure `region` in `createClient()`. For enterprise self-hosted deployments: configure `runtimeDomain`. Explicit `runtimeDomain` takes priority over `region`.

This document is for frontend and Node.js developers using @lovrabet/sdk, explaining how to select Mainland China or Indonesia Runtime endpoints, and how to connect to enterprise self-hosted Runtime instances.

SDK vs CLI Configuration

Product	Configuration Entry
Rabetbase / Lovrabet CLI	Via config init prompt or local JSON config.
Lovrabet Node SDK	No config init; doesn't read .rabetbase.json or .lovrabet.json proactively; pass config in createClient() in application code.

When generating projects via Rabetbase project templates, templates can write non-default region and runtimeDomain into SDK initialization code; at runtime, SDK only consumes the values passed to createClient().

Using Official Mainland China Endpoint

cn is the default country/region. Can be explicitly stated:

import { createClient } from "@lovrabet/sdk";

const client = createClient({
  appCode: "app-xxx",
  region: "cn",
  models: [],
});

Can also omit region; Mainland China is the default:

const client = createClient({
  appCode: "app-xxx",
  models: [],
});

Using Official Indonesia Endpoint

const client = createClient({
  appCode: "app-xxx",
  region: "id",
  models: [],
});

SDK resolves region to the corresponding official Runtime address. Currently only cn and id are supported; using other values throws INVALID_REGION and won't silently access other countries/regions.

Official Runtime Addresses by Region

Country/Region	region	Official Runtime Address
Mainland China	cn	https://runtime.lovrabet.com
Indonesia	id	https://runtime.lovrabet.id

Users only need to select country/region. Other address requirements are handled uniformly through explicit runtimeDomain, without exposing internal routing dimensions.

Enterprise Self-Hosted: Configure runtimeDomain

When enterprise Runtime uses a custom address, pass it directly in createClient():

const client = createClient({
  appCode: "app-xxx",
  runtimeDomain: "https://runtime.customer.example.com",
  models: [],
});

Once runtimeDomain is configured, it overrides the official address selected by region:

const client = createClient({
  appCode: "app-xxx",
  region: "id",
  runtimeDomain: "https://runtime.customer.example.com",
  models: [],
});

// Actual base address is still https://runtime.customer.example.com

Address Format Requirements

• Must be an absolute HTTP(S) address.
• Cannot contain credentials, query, or fragment.
• Leading/trailing whitespace and trailing slashes are normalized.
• HTTP is reserved for local development and limited compatibility scenarios; production and enterprise deployments should use HTTPS.

Browser Page Injection Configuration

Business pages generated by Lovrabet can inject the Runtime address at load time:

window.__GLOBAL__ = {
  deploymentConfig: {
    RUNTIME_API_DOMAIN: "https://runtime.customer.example.com"
  }
};

Application code doesn't need to pass runtimeDomain again:

const client = createClient({
  appCode: "app-xxx",
  models: [],
});

If code also passes runtimeDomain, code parameters take precedence over page injection values. This allows the same frontend build artifact to dynamically inject Runtime addresses for different deployment instances, while still allowing applications to explicitly override.

Full Resolution Priority

1. createClient({ runtimeDomain }): Official enterprise deployment config, highest priority.
2. serverUrl: Legacy field, kept for backward compatibility only; don't use in new code.
3. window.__GLOBAL__.deploymentConfig.RUNTIME_API_DOMAIN: Browser page injection.
4. region: Official country/region endpoint mapping.
5. Nothing passed: defaults to cn.

All SDK Services Share One Runtime Domain

Current SDK only supports runtimeDomain, not ocrDomain, fileDomain, or a generic serviceDomains. All these capabilities use the same Runtime base address:

• Data model CRUD and filter queries
• SQL and BFF
• OCR
• File upload and retrieval
• Other Runtime services

If an enterprise only deploys part of the Runtime services, SDK won't automatically fall back to Lovrabet official services for undeployed capabilities; requests still go to enterprise runtimeDomain, and the server explicitly returns "not deployed" or corresponding errors. When multiple address sets are needed, business applications should create different Clients or orchestrate themselves.

Authentication Mode Doesn't Change Domain

authMode determines the request path and auth headers, not the base address:

authMode	Typical Credentials	Domain
cookie	Browser cookie or explicit cookie	Still uses the same runtimeDomain / official Runtime
client-ak	accessKey	Still uses the same runtimeDomain / official Runtime
openapi	accessKey, or token + timestamp	Still uses the same runtimeDomain / official Runtime

When authMode is not set, cookie is the default; SDK doesn't automatically switch auth mode just because accessKey is configured.

Common Configuration Examples

Node.js with Enterprise Runtime and Client AK

const client = createClient({
  appCode: "app-xxx",
  authMode: "client-ak",
  accessKey: secureAccessKey,
  runtimeDomain: "https://runtime.customer.example.com",
  models: [],
});

Browser with Indonesia Endpoint and Cookie

const client = createClient({
  appCode: "app-xxx",
  authMode: "cookie",
  region: "id",
  models: [],
});

Verify Configuration

After initialization, read the final base address:

console.log(client.getBaseUrl());

Expected results:

• region: "id" → https://runtime.lovrabet.id
• region: "cn" → https://runtime.lovrabet.com
• Explicit runtimeDomain → Returns the normalized enterprise address

FAQ

Does SDK read Rabetbase CLI's config file? No. Project templates or application code need to pass region, runtimeDomain to createClient().

Can I configure both region and runtimeDomain? Yes, but runtimeDomain takes priority; region doesn't participate in current Client's address resolution.

What if different deployment instances have different enterprise Runtimes? Applications can read runtimeDomain from their own deployment config, then pass it to createClient(). SDK doesn't introduce additional public routing dimensions.

Can I still use serverUrl? For now, yes, but it's deprecated and has lower priority than runtimeDomain. Use runtimeDomain for all new code.

---

Applicable version: Verified against Lovrabet Node SDK main branch (package version 1.5.1-beta.0) as of 2026-08-23.