Edge Configuration
The edge reads all of its configuration from environment variables at startup. Restart it after any change.
Settings
| Variable | Set in production | Default | Description |
|---|---|---|---|
OCTET_URL |
Yes | A local address | The Octet API. Set it to https://geo.octetproof.com. If it is unset, the edge still starts, but every session fails with 502 octet_unreachable. |
LICENSE |
Yes | Unset | Your license token, octet_live_v4.public.…. See Credentials. |
ALLOWED_ORIGIN |
Yes | * |
The origins allowed to call the edge from a browser, comma-separated with no spaces, for example https://www.example.com,https://app.example.com. Applies to both the POST and the WebSocket. The default * allows any origin, so always set it in production. |
PORT |
Yes | 8080 |
The TCP port to listen on. Use 443 in production. |
EDGE_TLS_CERT_FILE |
Yes | Unset | Path to your TLS certificate chain in PEM format, such as a Let's Encrypt fullchain.pem. |
EDGE_TLS_KEY_FILE |
Yes | Unset | Path to the matching private key in PEM format, such as privkey.pem. |
EDGE_DEBUG |
No | Off | 1 or true logs one line per request, including the end-user's IP address. Use it only for short diagnostic sessions, and never leave it on in production. |
EDGE_CLIENT_CERT_FILE |
Yes | Unset | Mutual TLS to Octet. Path to your edge's client certificate, downloaded from your license's Edge configuration tab in the Octet portal, under Certificates. |
EDGE_CLIENT_KEY_FILE |
Yes | Unset | Mutual TLS to Octet. Path to the client certificate's private key. |
EDGE_SIGNING_KEY |
Yes | Unset | The edge's signing key: a base64 32-byte Ed25519 key, from openssl rand -base64 32. The edge signs each session it forwards with it. Unset, the edge forwards sessions unsigned and logs a warning at startup. See Edge signature. |
EDGE_SIGNING_KID |
No | Derived from the public key | The signing key's ID, kid, which you register with the public key. Up to 64 letters, digits, ., _ or -. The default is edge- followed by a hash of the public key. |
OCTET_CA_FILE |
No | Unset | Path to a CA certificate that Octet's server certificate must chain to. Unset, the edge checks Octet's server certificate against the host's system trust store. |
The edge serves HTTPS only when both EDGE_TLS_CERT_FILE and EDGE_TLS_KEY_FILE are set. Without them it serves plain HTTP, which browsers will refuse to use from an HTTPS page. It accepts TLS 1.2 and 1.3, with modern AEAD cipher suites only. It loads the certificate at startup, so restart it after each renewal.
Mutual TLS
The edge connects to Octet only over mutual TLS. It refuses to start if EDGE_CLIENT_CERT_FILE or EDGE_CLIENT_KEY_FILE is unset, or if OCTET_URL isn't https://. The one exception is an OCTET_URL on a loopback address, which is for local development. The log line names what is missing, for example OCTET_URL must be https:// (mTLS to octet is required). To get the certificate, see Deploy the Edge.
Octet's server certificate is a public certificate, so the edge verifies it with the host's system trust store. You don't need Octet's client CA certificate. Set OCTET_CA_FILE only if your security policy requires pinning Octet's server certificate to a specific CA.
The edge loads the client certificate and key at startup, so restart it after you renew them.
Edge signature
With EDGE_SIGNING_KEY set, the edge signs each session it forwards to Octet. The signature covers the collection and everything the edge adds about the connection. At startup the edge logs the key's kid and public key:
[octet-edge] S2 signing on: kid=edge-… ed25519 public key=… (register it in the licence portal)
Register both in your license's Edge configuration tab in the Octet portal, under Signing keys. If the value isn't a base64 32-byte key, the edge exits and logs EDGE_SIGNING_KEY must be a base64 32-byte Ed25519 seed.
Octet refuses a session whose signature fails its check. Octet is turning on required edge signatures, and from then on it also refuses an unsigned session, or one signed by a key that isn't registered for your license. The reason codes are in Errors. The signing key and the client certificate are separate credentials, and the edge needs both. See Credentials.
Testing only
The edge also reads two settings meant for testing. Leave both unset in production.
| Variable | Effect |
|---|---|
EDGE_EXPOSE_VERDICT |
1 or true makes the edge answer the collector's POST with the verdict's country, confidence and alarm instead of {"ok":true}. The signed token is never included. |
EXIT_IP |
Replaces the user's IP address with this value for every session. It is for local tests where the browser reaches the edge over loopback. |
Endpoints
| Method | Path | Called by | Response |
|---|---|---|---|
GET |
/health |
You, for monitoring | 200 {"ok":true,"role":"octet-edge"}. Does not contact Octet. |
POST |
/v1/signals |
The collector | 200 {"ok":true} when Octet accepted the session. Errors are in Errors. |
GET |
/v1/ws |
The collector | A WebSocket upgrade. It stays open for at most 15 seconds. |
OPTIONS |
/v1/signals |
The browser, for CORS | 204 with the CORS headers. |
The edge serves every path at its root, so apiUrl is the edge's origin with no path, for example https://octet.example.com.
Ports and connections
| Direction | Protocol and port | Peer |
|---|---|---|
| Inbound | TCP 443 | Browsers, for HTTPS and the WebSocket |
| Outbound | TCP 443 | geo.octetproof.com |
The edge must accept the browser's TCP connection directly. See Deploy the Edge.
Binaries
Each release contains static Linux binaries with no runtime dependencies:
| File | Platform |
|---|---|
octet-edge-linux-amd64 |
Linux on x86-64 |
octet-edge-linux-arm64 |
Linux on 64-bit ARM |
Check each binary against the release's SHA256SUMS before you install it. See Deploy the Edge. The edge runs only on Linux.