Configuration

Edge Connector Configuration

The Edge Connector is configured through a combination of a config.json file and environment variables. Environment variables always take precedence over config file values, which in turn take precedence over built-in defaults. This page covers all configuration options, file formats, and the precedence rules.

Precedence order

When the Edge Connector resolves a configuration value, it checks the following sources in order (highest priority first):

1. Environment variables — always override everything else.

2. config.json file — values from the configuration file in the working directory.

3. Built-in defaults — hardcoded fallback values used when no other source provides a value.

Environment variables

The following environment variables control Edge Connector behavior. All are optional; the Edge Connector works with default values for local development.

Connection and server

Variable	Default	Description
TOOL_RPC_URL	ws://localhost:3001	WebSocket URL for the nara platform server. This is the primary connection endpoint for all tool execution traffic. Use wss:// for production.
PLATFORM_API_URL	http://localhost:3000	Base URL for the nara platform API. Used for bundle management, authentication endpoints, and cloud connector operations.
NEXT_PUBLIC_TOOL_RPC_URL		Alternative to TOOL_RPC_URL. If TOOL_RPC_URL is not set, this value is used. Useful when sharing environment files with the webapp.
NEXT_PUBLIC_PLATFORM_API_URL		Alternative to PLATFORM_API_URL. Same precedence behavior.

Authentication

Variable	Default	Description
AUTH_TOKEN_PATH	./auth-token.json	Path to the file where the authentication JWT token is stored. Can be absolute or relative to the installation directory.
DEPLOYMENT_ID		Deployment identifier for cloud/server mode. When both DEPLOYMENT_ID and DEPLOYMENT_SECRET are set, the connector uses deployment credentials instead of JWT token authentication.
DEPLOYMENT_SECRET		Deployment secret for cloud/server mode. Must be set together with DEPLOYMENT_ID.
DEPLOYMENT_CREDENTIALS_PATH		Path to a file containing deployment credentials as an alternative to setting DEPLOYMENT_ID and DEPLOYMENT_SECRET individually.

Paths and directories

Variable	Default	Description
CUSTOM_IMPLEMENTATIONS_PATH	./custom-implementations/index.js	Path to the entry point of your custom tool implementations. The runtime loads implementations from this path at startup.
NARA_INSTALL_DIRECTORY	Current working directory	Root installation directory. Used for resolving relative paths (token file, lock file, shutdown file) and as the base for the process lock.

Runtime behavior

Variable	Default	Description
HEALTH_PORT	8080	Port for the HTTP health check server. Exposes /livez, /healthz, and /statusz endpoints.
EC_TEST_RUN		Set to 1 to enable test mode. Disables state persistence, autostart, and the system tray. Used by edge-connector run for local testing.
EC_DISABLE_STATE		Set to 1 to disable state persistence. The runtime will not save or restore its running state. Automatically enabled in test mode.
EC_DISABLE_AUTOSTART		Set to 1 to disable automatic startup on system boot. Automatically enabled in test mode.
EC_DISABLE_TRAY		Set to 1 to disable the system tray icon. Automatically enabled in test mode.
EC_CONNECTOR_TYPE	EDGE	Connector type identifier.
INSTANCE_TYPE		Set to E2E to register E2E test tools alongside regular tools. Used in end-to-end testing environments.

Config file (config.json)

The config.json file lives in the Edge Connector’s working directory. If it does not exist, the runtime copies a default configuration from the installation package.

Full schema:

{
  "toolRpcUrl": "ws://localhost:3001",
  "authTokenPath": "./auth-token.json",
  "customImplementationsPath": "./custom-implementations/index.js",
  "connectorType": "EDGE",
  "platformApiUrl": "http://localhost:3000",
  "deploymentId": null,
  "currentBundleId": null
}

Field reference:

Field	Type	Required	Description
toolRpcUrl	string	Yes	WebSocket URL for the nara platform server
authTokenPath	string	Yes	Path to the authentication token file (absolute or relative to install directory)
customImplementationsPath	string	Yes	Path to the custom implementations entry point
connectorType	"EDGE"	Yes	Connector type
platformApiUrl	string	No	Base URL for the nara platform API
deploymentId	string	No	Deployment ID (set when assigned to a deployment)
currentBundleId	string	No	Currently tracked bundle ID (set automatically by bundle checkout and upload)

Tip

When you download the Edge Connector from the webapp, config.json is pre-populated with your organization’s production URLs. You typically only need to modify it for local development.

Auth token file (auth-token.json)

The authentication token is stored as a JSON file. This file is created automatically by edge-connector auth and managed by the runtime.

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "savedAt": "2025-01-15T10:30:00.000Z"
}

Field	Type	Description
token	string	The JWT authentication token
savedAt	string	ISO 8601 timestamp of when the token was saved

The file is created with restrictive permissions (0600) to protect the token from unauthorized access.

Caution

Never share or commit your auth-token.json file. It contains a JWT that grants access to your organization’s Edge Connector tools and data.

Deployment credentials file

For server/cloud deployments, credentials can be stored in a file instead of environment variables:

{
  "deploymentId": "dep_abc123xyz",
  "deploymentSecret": "sec_9f8e7d6c5b4a..."
}

Set the DEPLOYMENT_CREDENTIALS_PATH environment variable to point to this file. The runtime reads the file at startup and uses the credentials for WebSocket authentication.

Platform API URL configuration

The platform API URL determines where the Edge Connector sends API requests for authentication, bundle management, and cloud operations. The URL is resolved in this order:

1. PLATFORM_API_URL environment variable

2. NEXT_PUBLIC_PLATFORM_API_URL environment variable

3. platformApiUrl field in config.json

4. Default: http://localhost:3000

For production deployments, this should be set to your nara instance URL (e.g., https://app.nara.de).

Example configurations

Local Development

{
  "toolRpcUrl": "ws://localhost:3001",
  "authTokenPath": "./auth-token.json",
  "customImplementationsPath": "./custom-implementations/index.js",
  "connectorType": "EDGE",
  "platformApiUrl": "http://localhost:3000"
}

Production Server

# Environment variables
TOOL_RPC_URL=wss://tool-rpc.nara.de
PLATFORM_API_URL=https://app.nara.de
DEPLOYMENT_ID=dep_abc123
DEPLOYMENT_SECRET=sec_xyz789
HEALTH_PORT=8080
EC_DISABLE_TRAY=1

Docker Container

ENV TOOL_RPC_URL=wss://tool-rpc.nara.de
ENV PLATFORM_API_URL=https://app.nara.de
ENV DEPLOYMENT_ID=dep_abc123
ENV DEPLOYMENT_SECRET=sec_xyz789
ENV HEALTH_PORT=8080
ENV EC_DISABLE_TRAY=1
ENV EC_DISABLE_AUTOSTART=1
ENV NARA_INSTALL_DIRECTORY=/app