Edge environment variables reference

This page is the complete, grouped reference of every environment variable that configures a logiccloud Control edge deployment. It is written so you can build and configure a custom logiccloud Control container with your own reverse proxy (no bundled Caddy) from this page alone.

If you only need to put an unmodified edge stack behind your own proxy under a path prefix, start with the concise walkthrough in Configuring an outbound proxy on the edge and the sections below.

Note

All processes in the edge container share one environment. The bootstrapper exports the IPC and reverse-proxy variables and spawns edge-admin and edge-connect, which inherit them. Set routing/RAM variables once for the whole container.

How to read this reference

• Read by names the component(s) that consume the variable (edge-admin, edge-connect, edge-bootstrapper, init.sh, or the shared edge settings library).
• Prefix-affected? indicates whether EDGE_ROUTE_PREFIX changes the variable’s behavior. Only routing variables are prefix-affected.

Orchestration and IPC

Variable	Default	Read by	Effect	Prefix-affected?
USE_UDS	false	all	Use Unix Domain Sockets for inter-process communication instead of TCP.	no
UDS_BASE_PATH	/var/run/logiccloud/ipc	init.sh, edge-connect, settings	Base directory for all IPC sockets.	no
RUNTIME_SOCKET_PATH	$UDS_BASE_PATH/runtime.sock	init.sh, edge-admin, settings	PLC runtime IPC socket.	no
LICENSING_SOCKET_PATH	$UDS_BASE_PATH/license-service.sock	init.sh, edge-admin, settings	License service IPC socket.	no
EDGE_ADMIN_SOCKET_PATH	$UDS_BASE_PATH/control.sock	init.sh, edge-admin, bootstrapper, settings	edge-admin listen socket (control.sock) — the primary upstream your proxy forwards to.	no
EDGE_CONNECT_SOCKET_PATH	$UDS_BASE_PATH/edge-connect.sock	init.sh	edge-connect (pairing UI) listen socket — the cold-start upstream used before a device is bound.	no
RUNTIME_TCP_PORT	45600	init.sh	Runtime TCP port when USE_UDS is not true.	no
LICENSING_TCP_PORT	45601	init.sh	License service TCP port when USE_UDS is not true.	no
EDGE_ADMIN_RUNTIME_HOST	localhost	settings	Runtime TCP host override.	no
EDGE_ADMIN_RUNTIME_PORT	45600	settings	Runtime TCP port override.	no
EDGE_ADMIN_RUNTIME_PROTOCOL	tcp	settings	Runtime protocol override.	no

Note

The RUNTIME_CONNECTIVITY_ARGS, LICENSING_CONNECTIVITY_ARGS, and LICENSING_SERVER_CONNECTIVITY_ARGS variables are derived and exported by the container entrypoint from the settings above. Do not set them yourself.

edge-admin

Variable	Default	Read by	Effect	Prefix-affected?
EDGE_ADMIN_PORT	18000	all	edge-admin HTTP listen port (TCP mode).	no
EDGE_ADMIN_STATIC_DIR	/app/storage/edge-admin-ui/current	edge-admin	Directory of the built edge-admin UI.	no
EDGE_ADMIN_INITIAL_ADMIN_PASSWORD	logiccloud	edge-admin, settings	Initial local admin password (first boot).	no
TARGET_NAME	edge-admin	edge-admin	Log target name for the supervisor process.	no
EDGE_ADMIN_IS_CLOUD	false	settings	Cloud-mode flag (vPLC image). Off for edge devices.	no
EDGE_ADMIN_IMPORT_FILE_PATH	—	settings	Optional device import file consumed at startup.	no
EDGE_ADMIN_LOG_MEMORY	—	settings	Enable memory-usage logging.	no
EDGE_DNS_HOST	—	edge-admin	Override the device DNS host reported to the portal (tests/dev).	no
LC_METRICS_HOST_DISK_ROOT	/	edge-admin	Mount path measured as the host root-disk gauge.	no
LC_METRICS_HOST_DISK_DATA	/data	edge-admin	Mount path measured as the host data-disk gauge.	no
LC_METRICS_CLK_TCK	system value	edge-admin	Override clock ticks/sec for CPU accounting.	no
LC_METRICS_EDGE_ADMIN_PER_CORE	true	edge-admin	Emit edge-admin CPU as per-core percentages.	no
LC_METRICS_SERVICE_PER_CORE	true	edge-admin	Emit per-service CPU as per-core percentages.	no

edge-connect

Variable	Default	Read by	Effect	Prefix-affected?
EDGE_CONNECT_STATIC_DIR	dist/edge-connect-ui	edge-connect	Directory of the built edge-connect (pairing) UI.	no
isDebug	false	edge-connect, settings	Debug mode (also disables outbound TLS verification). Note the lowercase-first spelling.	no

edge-connect also reads EDGE_ADMIN_PORT, STORAGE_FOLDER, EDGE_ROUTE_PREFIX, USE_UDS, UDS_BASE_PATH, and LOG_LEVEL, documented in their own groups.

Bootstrapper

Variable	Default	Read by	Effect	Prefix-affected?
CHILD_BINARY	/app/bin/edge-admin	bootstrapper	Path to the edge-admin binary.	no
EDGE_CONNECT_BINARY	./bin/edge-connect	bootstrapper	Path to the edge-connect binary.	no
LC_EDGE_CONTAINER_VERSION	—	bootstrapper, edge-admin, settings	Pinned container/bootstrapper version stamped into the device. edge-admin still auto-updates to the latest published version.	no
DEVICE_TOKEN	—	init.sh, bootstrapper, settings	Pre-provisioned device token. Its presence marks the device as already bound (warm start).	no
BOOTSTRAPPER_HEALTH_PORT	8081	bootstrapper	Port for the bootstrapper /healthz server (see Health and readiness).	no
EDGE_ADMIN_APP_FOLDER	/app	bootstrapper, settings	Override the app folder for edge-admin.	no

Reverse proxy and route prefix

Variable	Default	Read by	Effect	Prefix-affected?
EDGE_ROUTE_PREFIX	/ (no prefix)	edge-admin, edge-connect, settings	The single routing knob. See Route-prefix contract.	defines it
EDGE_ADMIN_PATH	/	edge-admin only	Vestigial edge-admin-only base-href override. Do not use for new deployments.	yes (edge-admin only)
USE_REVERSE_PROXY	—	init.sh, bootstrapper	caddy starts the bundled Caddy; any other value (for example none) disables it so your proxy can own the listen port.	no
REVERSE_PROXY_PORT	8080	init.sh, bootstrapper	Port the bundled Caddy listens on. Irrelevant when Caddy is disabled.	no
CADDY_CONFIG_PATH	$STORAGE_FOLDER/reverse-proxy	init.sh, bootstrapper	Directory holding the generated Caddyfiles. Bundled Caddy only.	no
CADDY_RELOAD_PATH	/usr/bin/caddy-reload.sh	bootstrapper	Path to the Caddy reload helper. Bundled Caddy only.	no
READINESS_GATED_PROXY	true	init.sh, bootstrapper	Serve a static “starting” page until edge-admin readiness passes, then flip. Set false to switch immediately.	no
EDGE_STARTING_DIR	$APP_FOLDER/starting	init.sh	Directory of the static loading page. Bundled Caddy only.	no

Health and readiness

Variable	Default	Read by	Effect	Prefix-affected?
BOOTSTRAPPER_HEALTH_PORT	8081	bootstrapper	TCP port for the bootstrapper-owned /healthz (kubelet liveness), decoupled from the reverse proxy and edge-admin.	no
EDGE_ADMIN_HEALTHZ_PATH	/healthz	edge-admin	Remap edge-admin’s own diagnostics health path. Always served at root, never under the route prefix.	no
EDGE_ADMIN_READYZ_PATH	/readyz	edge-admin	Remap edge-admin’s readiness path (the UI-bundle gate the bootstrapper polls to flip the proxy). Always served at root.	no

See Health and readiness topology for details.

Logging

Variable	Default	Read by	Effect	Prefix-affected?
LOG_LEVEL	3 (edge-admin), warn (others)	all	Log verbosity (0–5).	no
LOG_FILE	<APP_FOLDER>/logs/logiccloud-control.log	edge-admin	Explicit log file path override.	no
LC_LOG_MAX_SIZE_MB	5	edge-admin	Per-file size cap before truncation. Legacy alias LOG_MAX_SIZE_MB.	no
LC_LOG_TRUNCATE_KEEP_MB	1	edge-admin	Tail retained when a file hits its cap.	no
LC_LOG_MAX_BACKUPS	3	edge-admin	Retained backups (kept for compatibility).	no
LC_LOG_MAX_AGE_DAYS	7	edge-admin	Max age (kept for compatibility).	no
LC_LOG_DIR_BUDGET_MB	64	edge-admin	Directory-level byte budget the log janitor enforces.	no
LC_LOG_DIR_HIGH_WATER_PCT	80	edge-admin	High-water percent that triggers cleanup.	no
LC_LOG_DIR_LOW_WATER_PCT	50	edge-admin	Low-water percent the janitor cleans down to.	no
LC_LOG_DIR_INTERVAL_SEC	10	edge-admin	Janitor scan interval.	no
LC_LOG_DIR_MIN_HEADROOM_RATIO	2.0	edge-admin	Minimum tmpfs headroom ratio safety check.	no
NODE_TLS_REJECT_UNAUTHORIZED	verify (unset)	log upload, connectors	0 disables outbound TLS verification (escape hatch).	no

RAM and garbage collection

Variable	Default	Read by	Effect	Prefix-affected?
LOGICCLOUD_RAM_BUDGET_FRACTION	0.75	init.sh, runtime	Fraction of detected device RAM used as the device-wide budget.	no
LOGICCLOUD_RAM_BUDGET_MB	fraction-driven	init.sh, runtime	Pin an explicit device-wide RAM budget in MiB; overrides the fraction.	no
GOGC	75	init.sh, Go runtime	GC aggressiveness backstop.	no
GODEBUG	madvdontneed=1	init.sh, Go runtime	Return freed memory pages to the OS promptly (important on 32-bit ARM).	no

Caution

Do not set LOGICCLOUD_RAM_SHARE or LOGICCLOUD_RAM_TOTAL in the container environment — edge-admin stamps those per-process onto each child.

Timing and throttling

These tune on-device polling and delays. Defaults are auto-selected by detected RAM: constrained for devices with 512 MiB or less, otherwise normal. Any value you set overrides both.

Variable	Constrained	Normal	Effect
EDGE_PROCESS_STATE_INTERVAL_MS	15000	3000	Process-state forwarding interval.
EDGE_UNBIND_CHECK_INTERVAL_MS	60000	5000	Unbind-check interval.
EDGE_ONLINE_STATUS_INTERVAL_MS	8000	8000	Online-status forwarding (must stay below 10 s).
EDGE_DOWNLOAD_DELAY_MS	2000	0	Delay between downloads.
EDGE_BOOTSTRAP_DOWNLOAD_DELAY_MS	3000	0	Delay between bootstrap downloads.
EDGE_CONTROLLER_STARTUP_DELAY_MS	5000	0	Delay between controller startups.
EDGE_DEVICE_PROCESS_SYNC_INTERVAL_MS	60000	60000	Device/process reconcile interval.
EDGE_BOOT_STAGE_DELAY_MS	1000	0	Delay between boot stages.
EDGE_LOW_PRIORITY_SCRIPTS	true	false	Run device scripts at low OS priority.

All of these are read by the shared edge settings library and are not prefix-affected.

Shared folders

Variable	Default	Read by	Effect	Prefix-affected?
STORAGE_FOLDER	<CWD>/storage	all	Storage root for all on-device data.	no
APP_FOLDER	/app	all	Application root folder.	no
LOCAL_DEBUG	—	settings	When set, resolve APP_FOLDER to the current working directory (dev).	no

Route-prefix contract

EDGE_ROUTE_PREFIX is the single knob that drives routing across the whole edge stack. Set it once for the container and it governs edge-connect route mounting, edge-admin route mounting (UI, GraphQL, auth, log download), and the on-device <base href> in the served UI.

Normalization

1. A leading slash is added if missing.
2. Any trailing slash is stripped.
3. / (or unset) means no prefix — everything is served at root.

Value	Normalized	Effect
logiccloud	/logiccloud	Served under /logiccloud
/logiccloud	/logiccloud	Served under /logiccloud
/logiccloud/	/logiccloud	Served under /logiccloud
/ (or unset)	(empty)	Served at root, no prefix

Note

EDGE_ADMIN_PATH is vestigial: an edge-admin-only base-href override kept for backward compatibility. It does not coordinate with edge-connect or route mounting. Use EDGE_ROUTE_PREFIX instead.

Routes under the prefix vs at root

With EDGE_ROUTE_PREFIX=/logiccloud:

Under the prefix (forward these unmodified): the UI and all assets, /api/graphql (including the WebSocket upgrade), /api/auth/login, /api/auth/logout, GET/POST /login, and /download-log/....

At root — never prefixed: /readyz and /healthz.

Route	Consumer	Why it stays at root
/readyz	bootstrapper readiness gate (over the socket)	The bootstrapper polls /readyz at root to flip the proxy upstream. A prefixed /readyz would never answer and the loading page would hang.
/healthz	kubelet liveness on port 8081	Kubelet expects a fixed root path, decoupled from the proxy and edge-admin.

Health and readiness topology

• Bootstrapper :8081/healthz — kubelet liveness probe on the bootstrapper’s own port (BOOTSTRAPPER_HEALTH_PORT), deliberately decoupled from the reverse proxy and edge-admin so a busy edge-admin never fails liveness.
• edge-admin /readyz — the UI-bundle readiness gate. Returns 200 only when edge-admin can serve the UI; otherwise 503 with Retry-After. The bootstrapper polls this over the socket at root and flips the proxy upstream from the loading page to edge-admin once it is ready.
• edge-admin /healthz and edge-connect /healthz — lightweight diagnostics endpoints.
• EDGE_ADMIN_HEALTHZ_PATH / EDGE_ADMIN_READYZ_PATH — remap edge-admin’s health and readiness paths. Both are always served at root. If you rename them, route the renamed paths at root as well.

Base-href trailing-slash caveat

The on-device UI is patched at boot with a <base href> derived from EDGE_ROUTE_PREFIX, and it must carry a trailing slash:

<base href="/logiccloud/">

The browser resolves relative asset URLs against <base href>. With /logiccloud/, assets/index.js resolves to /logiccloud/assets/index.js (correct). Without the trailing slash it resolves to /assets/index.js at root, producing 404s. The trailing slash is re-added automatically at patch time; you do not set the base href directly.

Caution

EDGE_ROUTE_PREFIX is read in three places, and the shared settings library (lib/edge/settings) stores the value without normalization while edge-admin and edge-connect normalize it. Always supply an already-normalized value such as /logiccloud (leading slash, no trailing slash) to avoid divergence. This is tracked internally as LC-2890 / ADR-0071-1 (LC-2891).

Worked example: custom reverse proxy

Expose the UI at https://device.example.com/logiccloud/, forward /logiccloud/* unmodified to the edge-admin and edge-connect sockets, and keep /readyz and /healthz at root.

Minimal environment

# Routing: the single knob, already normalized (no trailing slash).
export EDGE_ROUTE_PREFIX=/logiccloud

# IPC over Unix sockets. UDS_BASE_PATH defaults to /var/run/logiccloud/ipc;
# the entrypoint derives control.sock (edge-admin) and edge-connect.sock.
export USE_UDS=true

# Disable the bundled Caddy so your proxy owns the listen port and TLS.
export USE_REVERSE_PROXY=none

Everything else uses defaults. Set DEVICE_TOKEN only for pre-provisioned (cloud) devices; a device paired interactively leaves it unset and uses edge-connect for pairing.

nginx (illustrative)

upstream edge_admin   { server unix:/var/run/logiccloud/ipc/control.sock; }
upstream edge_connect { server unix:/var/run/logiccloud/ipc/edge-connect.sock; }

server {
    listen 443 ssl;
    server_name device.example.com;

    # Root-only probes: never under the prefix.
    location = /readyz  { proxy_pass http://edge_admin; }
    location = /healthz { proxy_pass http://edge_admin; }

    # Everything under the prefix, forwarded unmodified. No trailing slash on
    # proxy_pass, so nginx keeps the original /logiccloud/... URI.
    location /logiccloud/ {
        proxy_pass http://edge_admin;          # use edge_connect during pairing
        proxy_http_version 1.1;                # GraphQL WebSocket upgrade:
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host       $host;
    }
}

Caution

Do not write proxy_pass http://edge_admin/; — the trailing slash strips the prefix, which this design avoids.

Verify

curl -sk -o /dev/null -w '%{http_code}\n' https://device.example.com/logiccloud/
curl -sk -o /dev/null -w '%{http_code}\n' https://device.example.com/logiccloud/assets/index.js
curl -sk -o /dev/null -w '%{http_code}\n' https://device.example.com/readyz

All three should return 200. If /logiccloud/ is 200 but assets 404, check the base-href trailing slash. If /readyz hangs, it is being routed under the prefix instead of root.