Skip to content
nara Documentation

Runtime

Runtime DESKTOP & SERVER

Process model

Section titled “Process model”

At its core the Edge Connector is a long‑running Node.js process that:

  • reads configuration from config.json and optional provisioning.json
  • loads your compiled implementations (usually from custom-implementations/dist/index.js)
  • opens a WebSocket to the Tool RPC server
  • executes tools when the platform routes invocations to this deployment

The same runtime powers both Desktop and Server connectors; the difference is how tokens and deployment credentials are obtained.

Desktop vs Server mode

Section titled “Desktop vs Server mode”
  1. Desktop mode
    • connectorType is DESKTOP (default).
    • The runtime launches a browser-based flow to obtain a short‑lived JWT issued by the nara platform.
    • It auto-registers a deployment and stores its credentials for reuse.
  2. Server mode
    • connectorType is SERVER.
    • You supply a long‑lived admin token and deployment credentials via config or environment variables.
    • Ideal for headless servers, containers, and production workloads.

Configuration

Section titled “Configuration”

The runtime combines defaults, provisioning.json, config.json, and environment overrides.

Important fields:

  • toolRpcUrl – WebSocket URL of the Tool RPC server (e.g. wss://tool-rpc.your-company.com)
  • authTokenPath – path to the stored auth token file
  • deploymentCredentialsPath – path to deployment credentials file
  • customImplementationsPath – path to the compiled implementations entrypoint
  • connectorType – DESKTOP or SERVER
  • platformApiUrl / desktopAuthBaseUrl – HTTP base URL for desktop auth and bundle updates

Environment overrides (for scripted deployments or tests):

  • TOOL_RPC_URL / NEXT_PUBLIC_TOOL_RPC_URL
  • AUTH_TOKEN_PATH
  • DEPLOYMENT_CREDENTIALS_PATH
  • CUSTOM_IMPLEMENTATIONS_PATH
  • DEPLOYMENT_ID, DEPLOYMENT_SECRET
  • PLATFORM_API_URL, NEXT_PUBLIC_PLATFORM_API_URL, DESKTOP_AUTH_BASE_URL

Set EC_E2E_ENV_OVERRIDES=1 to force the runtime to honor these overrides.

Autostart and auto-updates

Section titled “Autostart and auto-updates”
  • On non-test runs the connector enables OS-level autostart so it comes back after reboot.
  • When desktopAuthBaseUrl or platformApiUrl is present and a bundle is embedded, the runtime periodically:
    • checks for a newer bundle version for the deployment,
    • downloads and extracts it,
    • reloads implementations without changing deployment identity.