This page is for administrators and engineers running an enterprise self-hosted deployment. It explains how to point the login, platform API, runtime, SkillHub, and knowledge base requests of the Lovrabet Runtime CLI at your company's own HTTPS services.

INFO

This page covers only the self-hosted connection scheme.

Related docs

• Lovrabet Runtime CLI .lovrabet.json configuration reference: every config field, scoping, and merging rules.
• Region nodes & custom API domains: first-time initialization, country/region selection, and partial service overrides.

TIP

If every request must stay inside the corporate network, all five domains must be configured. With only some of them set, the services you leave blank fall back to Lovrabet's mainland China official addresses.

What each of the five domains carries

Field	Request scope	What the deployment side must provide
userDomain	Login and user services	Access Key self-service creation and user-related endpoints
apiDomain	Platform API	Platform management endpoints, e.g. notification channel configuration
runtimeDomain	Common runtime, data, SQL, BFF, and file services	Runtime APIs, SDK requests, and file upload/download
skillDomain	SkillHub	Skill queries, downloads, and related endpoints
kbDomain	Knowledge base	Knowledge base listing, detail, retrieval, and write endpoints

An enterprise can expose a separate entry for each of the five services, or point all five fields at the same unified gateway. The CLI only accepts HTTPS origins; the concrete paths are decided jointly by CLI requests and gateway routing.

Pre-deployment checklist

• Every entry must use HTTPS. An internal corporate CA is fine, but every machine running the CLI must trust the corresponding certificate chain.
• Domains are origins only, e.g. https://runtime.example.com — no paths, query strings, fragments, usernames, or passwords.
• DNS, VPN, dedicated lines, and firewalls must allow employee machines and CI runners to reach these entries.
• The gateway must preserve authentication headers and correctly forward X-User-AK and X-Invoke-Source.
• File uploads, file downloads, SQL, and BFF requests can run long — do not impose aggressive timeouts or small request-body limits at the gateway layer.
• All five entries receive authentication requests for their own services; configure only addresses your enterprise trusts.

Recommended scheme: route all five request classes into enterprise services

Prepare the domain file

Create lovrabet-domains.json. This is standard JSON you can use directly:

{
  "userDomain": "https://user.example.com",
  "apiDomain": "https://api.example.com",
  "runtimeDomain": "https://runtime.example.com",
  "skillDomain": "https://skills.example.com",
  "kbDomain": "https://kb.example.com"
}

The annotated version below is for reading only and cannot be saved as JSON as-is:

{
  // HTTPS origin of the login and user services
  // The self-service Access Key creation URL is derived from it
  "userDomain": "https://user.example.com",

  // HTTPS origin of the platform API
  // Carries platform management requests
  "apiDomain": "https://api.example.com",

  // HTTPS origin of the common runtime
  // Runtime requests for data, SQL, BFF, files, etc. land here
  "runtimeDomain": "https://runtime.example.com",

  // HTTPS origin of SkillHub
  // Carries Skill queries, downloads, and related requests
  "skillDomain": "https://skills.example.com",

  // HTTPS origin of the knowledge base service
  // Carries knowledge base listing, detail, retrieval, and write requests
  "kbDomain": "https://kb.example.com"
}

Use a unified gateway

If the enterprise exposes a single entry, set all five fields to the same origin and let the gateway route by request path to the internal services:

{
  "userDomain": "https://lovrabet.example.com",
  "apiDomain": "https://lovrabet.example.com",
  "runtimeDomain": "https://lovrabet.example.com",
  "skillDomain": "https://lovrabet.example.com",
  "kbDomain": "https://lovrabet.example.com"
}

TIP

Do not bake a gateway sub-path into the domain — https://lovrabet.example.com/runtime will be rejected. If you need sub-path based traffic splitting, configure the routing inside the gateway against the actual request paths.

Write the global connection config

lovrabet config init --domain-config ./lovrabet-domains.json

config init always updates the global file ~/.lovrabet.json — no --global needed. It removes the existing country/region selection and the five explicit domains, then writes the values you provide; the Access Key, output format, risk level, and app bindings are preserved.

You can also pass flags directly. Explicit flags override same-named fields from the file:

lovrabet config init \
  --user-domain https://user.example.com \
  --api-domain https://api.example.com \
  --runtime-domain https://runtime.example.com \
  --skill-domain https://skills.example.com \
  --kb-domain https://kb.example.com

Store the Access Key

Keep the Access Key out of the domain file. Once the connection config is in place, complete authentication separately:

# Without an Access Key, prints the creation URL for the current userDomain
lovrabet auth login --non-interactive

# Once you have the Access Key, store it in the global config
lovrabet auth login --access-key YOUR_ACCESS_KEY

# Confirm which user the current credential belongs to
lovrabet auth info

The final .lovrabet.json example

Below is a typical complete global config for a self-hosted deployment. The real file must be standard JSON, comments removed:

{
  // Default app alias; used first when no --app or --appcode is passed
  "defaultApp": "crm",

  // Local app aliases; keep only stable App Code mappings
  "apps": {
    // crm is a local alias — name it after your business
    "crm": {
      // The Lovrabet App Code this alias points to
      "appcode": "app-crm-001"
    }
  },

  // Credential of the Runtime CLI; never commit to Git or share it around
  "accessKey": "YOUR_LOVRABET_ACCESS_KEY",

  // Default output format: compress, json, or pretty
  "format": "compress",

  // Default page size for commands that support pagination
  "pageSize": 50,

  // Highest risk level allowed to run: read, write, or high-risk-write
  "riskLevel": "write",

  // App localization setting; not the CLI interface language, not consumed yet
  "locale": "en-US",

  // HTTPS origin of the login and user services
  "userDomain": "https://user.example.com",

  // HTTPS origin of the platform API
  "apiDomain": "https://api.example.com",

  // HTTPS origin of the common runtime, data, SQL, BFF, and file services
  "runtimeDomain": "https://runtime.example.com",

  // HTTPS origin of the SkillHub service
  "skillDomain": "https://skills.example.com",

  // HTTPS origin of the knowledge base service
  "kbDomain": "https://kb.example.com"
}

A fully isolated self-hosted config needs no region. If the global file still carries one, the explicit domains still win for their services — but rebuilding once via config init --domain-config is recommended so the config states its intent clearly.

Verify the configuration took effect

Check the resolved result first

lovrabet config list
lovrabet doctor

config list shows the merged config with sensitive values masked; doctor shows the finally resolved country/region and the five API endpoints. Both only prove the local resolution — they do not replace real connectivity checks.

TIP

The current directory's ./.lovrabet.json takes precedence over the global file. If the addresses doctor shows don't match your expectations, first check whether the current directory sets the same-named domains.

Make one real request per request class

Target	Suggested command	Pass criteria
userDomain	lovrabet auth login --non-interactive	The returned Access Key creation URL belongs to the enterprise entry
apiDomain	lovrabet notification config-list --type EMAIL --appcode <APP_CODE>	Returns business JSON, not gateway HTML or a 404
runtimeDomain	lovrabet app list --no-cache	Reads apps from the enterprise runtime service
skillDomain	lovrabet skill list --scope all	Returns a Skill list
kbDomain	lovrabet kb list --appcode <APP_CODE> --format compress	Returns a knowledge base list

Feature modules of a deployment may be trimmed per license. When a command returns an explicit "no permission" or "feature not enabled", the request has already reached the business service; connection timeouts, certificate errors, gateway HTML, and path-level 404s are the actual access-layer problems.

Hybrid routing and partial self-hosting

Some enterprises bring only one class of services into their own network and let the remaining requests keep using the official service of a chosen country/region. In that case, initialize the official country/region first, then override exactly one domain:

# First pin the official country/region used by non-overridden services
lovrabet config init --region id

# Route only runtime traffic into the enterprise service
lovrabet config set runtimeDomain https://runtime.example.com --global

# Check the final result
lovrabet doctor

If the non-overridden services should use the mainland China official addresses, change the first line to lovrabet config init --region cn.

Do not build this hybrid scheme from a --domain-config file containing a single field. Entering self-hosted mode clears the existing country/region and domains; services left blank then fall back to the mainland China official addresses, which may not be what you intended.

Troubleshooting

Symptom	What to do
Domain validation fails	Confirm you used an HTTPS origin and removed the path, query string, fragment, and anything else beyond the bare origin.
"Unknown field" error	lovrabet-domains.json allows only the five domain fields — no Access Key, app, or output settings.
Certificate errors	Check certificate names, validity, and the full chain; with an internal CA, add it to the trust store of every machine and CI runner running the CLI.
HTML or a gateway login page comes back	Check that the gateway forwards API paths to the business services and does not redirect CLI requests into a browser login flow.
401 or 403	Run lovrabet auth info to verify the identity, then confirm the gateway preserves auth headers and the Access Key belongs to this self-hosted deployment.
Some requests still hit official addresses	Run lovrabet doctor and check the five final endpoints; full isolation requires all five domains, and conflicting overrides in the current directory must be cleaned up.
Timeouts or large-file failures	Check DNS, VPN, firewalls, reverse-proxy timeouts, request-body limits, and upstream connection pools.

Rolling back to the official service

Rolling back clears the five explicit global domains and switches to the official service of the chosen country/region:

# Roll back to the mainland China official service
lovrabet config init --region cn

# Or switch to the Indonesia official service
lovrabet config init --region id

# Verify the final endpoints
lovrabet doctor

config init does not delete the Access Key, output format, or app bindings. If the service you switched to does not accept the original Access Key, run lovrabet auth login --access-key <ACCESS_KEY> to update the credential.

Delivery checklist

• DNS, certificates, and gateway routing are in place for all five domains.
• If the enterprise requires full isolation, none of the five fields is missing.
• The domain file contains no Access Key, and no real credential has landed in Git, tickets, or shared documents.
• The five endpoints shown by lovrabet doctor match the delivery sheet.
• Each of the five request classes has completed at least one real request, with failures classified into access-layer vs. business-authorization problems.
• The rollback commands to cn or id have been written down.