Configuration & authentication

Config file

The connector reads <installDir>/config.json. The install directory is NARA_INSTALL_DIRECTORY if set, otherwise the current working directory. On first run the file is created from config.default.json.

Key	Description
toolRpcUrl	WebSocket URL of the Tool RPC server.
authTokenPath	Path to the auth token file (default ./auth-token.json).
customImplementationsPath	Path to custom tool implementations (default ./custom-implementations/index.js).
connectorType	Connector type (EDGE).
platformApiUrl	Platform API base URL.
deploymentId	Deployment this connector belongs to.
currentBundleId	Currently active tool bundle.

Environment overrides

Variable	Description
TOOL_RPC_URL	Override toolRpcUrl.
PLATFORM_API_URL	Override platformApiUrl.
AUTH_TOKEN_PATH	Override authTokenPath.
DEPLOYMENT_ID / DEPLOYMENT_SECRET	Cloud deployment credentials (headless, no browser auth).
HEALTH_PORT	Health server port (default 8080).
EC_DISABLE_TRAY	Disable the system tray icon.

Authentication

The runtime picks its authentication mode automatically: if DEPLOYMENT_ID and DEPLOYMENT_SECRET are set it runs in cloud deployment mode without any browser interaction; otherwise it uses a saved token or starts the browser device flow. Failed auth is retried with a backoff from 30 to 300 seconds.

Browser device flow

The connector requests a verification code and opens your browser to the desktop authorization page (/edge/desktop/verify), which shows the code. Click Approve in the webapp to authorize the device. The connector polls for the session token and times out after 2 minutes. On Windows, the tray menu shows a Login item while the connector is unauthenticated.

Token flow

Pass an existing JWT (or a path to a token file) directly:

edge-connector auth -t <token>

The token must be unexpired and include organization information. It is saved to the authTokenPath with file mode 0600.

Runtime behavior

• Connect and retry — connection attempts back off from 5 seconds, doubling up to 60 seconds, for a maximum of 10 attempts. A heartbeat/reconnect check runs every 30 seconds.
• Bundle sync — the runtime checks for bundle updates every 10 minutes and on push notification. Updates compare checksums, download, swap the dist directory atomically, then reload and re-register tools.
• Built-in diagnostics — getSystemInfo, getResourceUsage, and getTopProcesses are always available and cannot be overridden.
• Health endpoints — an HTTP server on HEALTH_PORT (default 8080) serves /livez, /healthz (returns 503 while starting), and /statusz (connection state, last connection error, webhook relay state).