Engine Network Access

LexiEngine Network Access

LexiEngine is loopback-only by default. A public TCP bind is refused with the same diagnostic as before:

invalid request: cleartext engine HTTP may bind only loopback; use a TLS reverse proxy for remote access

A remote client has two explicit transport choices. The choices apply to the native single-model serving entry point (including its composed image and media routes). They do not enable public access for the separate multi-model router or the experimental SDAR CPU entry point.

TLS in the engine

Provide a server certificate chain in PEM format and its matching PKCS#8 private key, then choose an address reachable from the client:

lexi-engine serve -m MODEL.gguf --host 0.0.0.0 --port 8081 \
    --tls-cert engine-cert.pem --tls-key engine-key.pem

Use an HTTPS base URL in the client. Trust the issuing CA or explicitly trust the certificate. The server authenticates its certificate to clients; TLS alone does not authenticate each API client. If clients should also be authenticated, add --api-key or --api-key-file and send an Authorization: Bearer ... header or X-API-Key header.

The TLS key file must be regular, must not be a symlink, and must be owner-readable and inaccessible to other users on Unix systems. The server validates both files and their matching key before binding. Invalid or incomplete credentials refuse startup; one TLS flag without the other is an error. TLS traffic terminates in the engine using the first-party TLS state machine, then passes to the engine's existing bounded HTTP/1.1 router via a loopback-only internal transport. Clients must use HTTPS on the configured listener, not HTTP.

Current restriction: the implemented server-side handshake supports TLS 1.3 only. It rejects TLS 1.1 and TLS 1.2 handshakes, including TLS 1.2 clients that omit extended master secret. A secure TLS 1.2 server handshake with mandatory extended master secret is not yet implemented; do not advertise TLS 1.2 server compatibility. Client-side TLS 1.2 support in the shared TLS crate is a separate feature.

Authenticated cleartext LAN

For clients that require plain HTTP on a trusted private network, opt in and supply an API credential explicitly:

lexi-engine serve -m MODEL.gguf --host 0.0.0.0 --port 8081 \
    --allow-cleartext-lan --api-key-file engine-api-keys.txt

The key file is a private, non-symlink UTF-8 file with one validated key per line. --api-key is also accepted, but a file avoids publishing secrets in a process argument list. A key supplied only through an environment variable or unrelated decision credentials is insufficient to activate cleartext LAN mode; an explicit --api-key or --api-key-file is required. The server refuses empty/invalid keys.

All registered endpoints are protected in this mode, including /health, /v1/health, /version, /ping, /metrics, and CORS preflight requests. Missing or incorrect keys receive HTTP 401 Unauthorized. Normal loopback mode keeps existing health behavior. --allow-cleartext-lan cannot be combined with --tls-cert/--tls-key.

Plain HTTP provides no confidentiality or integrity against network eavesdropping or interception. The startup log emits a one-line warning that LAN traffic is unencrypted. Use this option only within a network where the consequences of exposed prompts, responses, and API keys are understood. TLS is the preferred mode for remote access.

Operational notes

• The --host, --bind, and --port options retain their existing address selection and duplicate-address behavior; all public sockets are bound before serving.
• TLS currently uses HTTP/1.1, not HTTP/2. Use a valid server certificate and configure the client to verify it.
• Authentication is scoped to the configured instance. An API key for one service does not automatically grant access to another.
• A private ephemeral loopback port is created for the TLS-to-HTTP transport. Local processes on the same host can access the loopback HTTP transport while the TLS listener is active; enforce host-local trust accordingly.
• The Panel's instance-launch code is unchanged; it can forward the new engine command-line flags when its own control is wired.
• Hardware and external-client interoperability still require testing on the target system. The provided TLS tests use in-memory Unix socket pairs rather than physical or LAN networking.