Edge Configuration

In one sentence

Every environment variable and endpoint of the octet-edge binary, in one place.

Environment variables

The edge is configured entirely through the environment.

Variable	Required	Default	Purpose
OCTET_URL	yes (prod)	http://127.0.0.1:8787 (dev fallback)	Octet's API base URL the edge forwards to — Octet provides it. If unset, the edge falls back to a local dev address — see the warning below.
LICENSE	prod	(unset)	Your license key. Sent to Octet as the x-octet-license header. Unset → not sent.
ALLOWED_ORIGIN	recommended	* (any origin)	The browser origin allowed to call the edge (CORS) and open the latency WebSocket. Set to your site's origin in production, e.g. https://yourapp.com. Default * allows any origin.
PORT	no	8080	Port the edge listens on. Set to 443 when the edge serves HTTPS directly — see EDGE_TLS_CERT_FILE.
EDGE_TLS_CERT_FILE	recommended	(unset)	Path to the TLS certificate chain (e.g. a Let's Encrypt fullchain.pem). Set together with EDGE_TLS_KEY_FILE to have the edge serve HTTPS itself, so it is the hop that terminates the browser's connection — see Serving HTTPS at the edge below. Both unset → plain HTTP.
EDGE_TLS_KEY_FILE	recommended	(unset)	The matching TLS private key (e.g. privkey.pem). Required alongside EDGE_TLS_CERT_FILE; setting only one has no effect.
EDGE_EXPOSE_VERDICT	no	off	Whether the edge returns the verdict to the browser. Leave off in production — the browser then receives only an { "ok": true } ack and your backend fetches the verdict server-to-server. Set 1 / true for demos/testing only. See Verdict delivery below.
EXIT_IP	no	(unset)	Testing only. Overrides the harvested source IP, for local setups where the browser↔edge connection is loopback. Leave unset in production.
EDGE_DEBUG	no	off	Diagnostics only. Logs one line per request including the end-user's source IP and the connection-level timing observation — useful for confirming the edge is the connection-terminating hop. Leave off in production (it logs end-user IPs). Set 1 / true to enable.
OCTET_CA_FILE	optional	(unset)	Path to Octet's CA certificate. Pins and verifies Octet over HTTPS. For the planned mutual TLS — optional and inert until Octet provisions certs.
EDGE_CLIENT_CERT_FILE	optional	(unset)	Your client certificate for mutual TLS to Octet. Planned hardening — not required yet.
EDGE_CLIENT_KEY_FILE	optional	(unset)	The matching private key. Planned hardening — not required yet.

Always set OCTET_URL in production

If OCTET_URL is left unset, the edge silently falls back to a local development address (http://127.0.0.1:8787). It does not error on startup — instead every request fails with 502 octet_unreachable, with no other hint that the variable is missing. Set it to the URL Octet gave you.

Serving HTTPS at the edge (browser → edge). Set EDGE_TLS_CERT_FILE + EDGE_TLS_KEY_FILE (e.g. a Let's Encrypt fullchain.pem + privkey.pem) and PORT=443 to have the edge terminate the browser's TLS connection itself. This is the cleanest way to satisfy the one rule: the edge becomes the hop the browser's connection terminates on, so the connection-level timing signal is measured against the browser rather than an intermediary. With both unset the edge serves plain HTTP — for development, or when it sits behind a connection-preserving front you've verified (see Cloud LB / CDN). A standalone TLS recipe is in Edge standalone / container.

TLS to Octet (edge → Octet). The edge reaches Octet at OCTET_URL (use https://). Mutual TLS is planned hardening and not yet in force — the OCTET_CA_FILE / EDGE_CLIENT_CERT_FILE / EDGE_CLIENT_KEY_FILE variables are optional and inert until Octet provisions certificates. When provided, OCTET_CA_FILE pins and verifies Octet over HTTPS, and adding the client certificate + key enables mutual TLS.

Verdict delivery. By default (EDGE_EXPOSE_VERDICT off) the browser receives only an opaque { "ok": true } ack — never the verdict. Your backend reads the authoritative result server-to-server with GET /v1/verdict/:ref — keyed by the sessionRef you minted, authenticated with your partner key — and applies your policy. Setting EDGE_EXPOSE_VERDICT=1 returns the coarse { country, confidence, alarm } to the browser instead — convenient for demos, but the browser is untrusted, so keep it off in production.

Endpoints

Method	Path	Purpose
GET	/health	Liveness check. Returns { "ok": true, ... }.
POST	/v1/signals	The collector posts the signal bundle here. The edge forwards it to Octet and returns a coarse result. Requires Content-Type: application/json.
GET	/v1/ws	WebSocket latency channel the collector measures against.

Paths are relative to wherever you mount the edge. With the collector's apiUrl: 'https://yourapp.com/octet', route /octet/* to the edge so /octet/v1/signals reaches /v1/signals. See the per-server guides.

Notes

• The edge is Linux-only for the connection-level timing signal — it relies on a capability available only on Linux. A non-Linux build runs for development but omits that signal.
• The edge is logic-free — it harvests connection-level signals and forwards. It holds no rules or thresholds.

Where to go next

• Deploy the Edge. The deployment walkthrough.
• Licensing. Where LICENSE comes from.