Skip to content

lan_web_ui_design.md

Latest commit

 

History

History
248 lines (183 loc) · 7.46 KB

lan_web_ui_design.md

File metadata and controls

248 lines (183 loc) · 7.46 KB
Raw

LAN Web UI Design

Release

  • Added in v6.28.0.
  • Docs-only design for a possible future LAN Web UI.
  • No Swift source, web server, routes, browser UI, authentication code, networking code, tests, app binary, or release asset is added in this release.

Purpose

v6.28.0 defines the safety boundary for a possible future LAN Web UI before any implementation work starts.

The LAN Web UI is a future remote operations surface for trusted local-network use. It must not become an inference proxy, internet exposure feature, hosted service, multi-backend router, or chat application.

The core Direct Mode path remains unchanged:

OpenAI-compatible client -> mlx_lm.server

The app may observe and control the managed server through existing app services. A LAN Web UI may only expose a carefully bounded view of that same app state through a separate adapter.

Current State

Current project state:

  • LAN Web UI is not implemented.
  • The app does not run a web server.
  • The app does not expose remote routes.
  • The app does not proxy inference requests.
  • The app does not provide browser-based chat.
  • The app does not expose logs or settings over the network.
  • The app does not implement account management or remote authentication.

Existing architecture already treats LAN Web UI as a future extension point, separate from Direct Mode and separate from Proxy mode.

Design Goals

A future LAN Web UI should:

  • be disabled by default;
  • require an explicit local opt-in;
  • bind to loopback by default for first implementation;
  • require strong local-network access controls before LAN binding is allowed;
  • expose a small status-first operations surface;
  • avoid exposing secrets, tokens, full local paths, private logs, prompts, responses, or generated client configuration;
  • reuse existing view-model or service state through a separate adapter;
  • preserve the existing desktop app as the primary control surface;
  • make shutdown and disabling obvious;
  • clearly state that internet exposure is unsupported.

Non-Goals

v6.28.0 does not approve:

  • a public internet dashboard;
  • cloud-hosted access;
  • reverse tunnel support;
  • automatic router or firewall configuration;
  • inference proxying;
  • /v1/chat/completions forwarding;
  • browser chat UI;
  • multi-user accounts;
  • remote model downloads;
  • remote model deletion;
  • remote cache cleanup;
  • remote file browsing;
  • remote shell execution;
  • telemetry;
  • analytics;
  • background monitoring beyond explicit app state display;
  • release automation.

Initial Surface Scope

A safe first LAN Web UI should be read-only unless a separate implementation plan approves actions.

Read-only candidate content:

  • app-managed server state;
  • selected profile display name;
  • compact current target summary;
  • readiness state;
  • bounded memory summary;
  • bounded recent app-side log summaries;
  • current Direct Mode reminder;
  • whether the current target is app-managed or external/adopted.

Do not expose:

  • API keys;
  • Hugging Face tokens;
  • full home paths;
  • raw process output;
  • prompts or completions;
  • environment variables;
  • generated client configuration persistence;
  • full settings files;
  • model cache contents;
  • file browser views.

Action Scope

A first implementation should avoid remote actions.

If actions are later considered, they require a separate design and should begin with only:

  • view current state;
  • copy-safe display values;
  • stop LAN Web UI locally from the desktop app.

Remote Start, Stop, Restart, profile editing, model download, model deletion, cache cleanup, and external server adoption should remain out of scope until explicit review.

Binding Policy

Recommended staged binding policy:

  1. First implementation binds only to 127.0.0.1.
  2. LAN binding requires a separate explicit setting.
  3. LAN binding must show the chosen host and port in the desktop app.
  4. LAN binding must have a visible disable action.
  5. LAN binding must not auto-start on app launch unless a later release explicitly adds and documents that behavior.
  6. Public internet binding is unsupported.

Do not infer that a host such as 0.0.0.0 is safe. It should be treated as an advanced and risky setting if ever allowed.

Access Control

Before LAN binding is implemented, define at least one local access control mechanism.

Acceptable future candidates:

  • one-time pairing code shown only in the desktop app;
  • local-only shared secret generated by the app;
  • temporary session token with short lifetime;
  • allowlist of local subnet addresses if implemented carefully.

Not acceptable:

  • no authentication for LAN access;
  • default shared password;
  • committing credentials;
  • storing secrets in docs, fixtures, screenshots, or release assets;
  • sending secrets to analytics or external services.

Adapter Boundary

A future LAN Web UI adapter should consume safe app state through a narrow interface.

It should not:

  • own process launch logic;
  • duplicate Process handling;
  • parse raw command output directly;
  • bypass view models or services;
  • directly mutate settings files;
  • persist generated client config;
  • become part of the inference request path.

Recommended adapter shape:

App services / view models -> LANWebUIStateAdapter -> local HTTP surface

The adapter should expose already-redacted summaries, not raw internals.

Privacy And Redaction

Any future LAN Web UI content must be copy-safe by default:

  • compact user paths to ~/... when paths are necessary;
  • omit tokens and secrets;
  • omit raw command output;
  • omit private URLs;
  • omit prompts and model responses;
  • omit environment variables;
  • bound log output;
  • mark external targets as not managed by MLX Server Manager.

UI Wording

Use conservative wording:

LAN Web UI is off.

LAN Web UI is local-network access to app status only.

Internet exposure is not supported.

This does not proxy inference requests.

External server targets are not managed by MLX Server Manager.

Verification Expectations

A future implementation should verify:

  • LAN Web UI is disabled by default;
  • no listener starts on app launch unless explicitly enabled by the user;
  • loopback binding works before LAN binding is considered;
  • LAN binding shows visible status in the desktop app;
  • disabling the feature closes the listener;
  • exposed status is copy-safe;
  • no secrets, tokens, full paths, prompts, responses, raw process output, settings files, or model files are exposed;
  • no inference requests are proxied;
  • no /v1/chat/completions request is sent;
  • app-managed and external targets remain clearly distinct;
  • Direct Mode remains direct.

Implementation Entry Criteria

Start implementation only when:

  • first implementation scope is read-only or explicitly reviewed;
  • default binding is selected;
  • access control policy is selected;
  • redaction helper is available or planned;
  • adapter boundary is defined;
  • tests can run without real secrets, real LAN exposure, or user-specific paths;
  • release notes can accurately state that the feature is local-only and not an inference proxy.

Release Acceptance

v6.28.0 is acceptable if:

  • this design document is added;
  • README references the design;
  • docs/tasks.md records the completed docs-only work;
  • no Swift source files change;
  • no tests change;
  • no web server is added;
  • no route is added;
  • no authentication implementation is added;
  • no network listener is added;
  • no app binary zip is produced;
  • no runtime behavior changes;
  • Direct Mode remains unchanged.