AFM bundles the llama.cpp chat interface, serves it from the same local process as the API, and adds AFM model discovery, branding, attachment support, and a live metrics panel. It is a convenient client of AFM—not a separate inference runtime.
Start the interface
# Small MLX text model
afm mlx -m Qwen3-0.6B-4bit --webui
# Apple Foundation Models
afm --webui
# DwarfStar executor checkpoint
afm mlx -m /path/to/executor-checkpoint --mlx-runtime dwarfstar --webui-w is the short form of --webui. AFM normally opens the default browser after the server is ready. If browser launch fails, open the printed server URL manually—normally http://127.0.0.1:9999/. The API remains below /v1.
What the WebUI adds
| Surface | Behavior | Backend boundary |
|---|---|---|
| Streaming chat | Renders incremental content and reasoning returned by /v1/chat/completions. | Streaming must not be disabled at server startup. |
| Model picker | Reads /v1/models; AFM remembers the preferred model in browser local storage. | A single-model MLX or DwarfStar server still has one active chat checkpoint. |
| Gateway discovery | Shows Foundation Models plus discovered Ollama, LM Studio, Jan, or compatible backends. | The external backend still owns model loading and execution. |
| Generation controls | Uses /props to initialize context and sampling controls. | A visible control is not proof that every backend implements the corresponding parameter. |
| Image and PDF attachment | Sends browser-selected media as multimodal message content. | Requires Foundation vision or an MLX VLM started with --vlm. DwarfStar is text-only. |
| Live metrics | The right-edge chart button opens a non-modal panel that polls /metrics once per second while open. | It adds measurement traffic and displays process-wide, not conversation-private, statistics. |
Read the metrics panel
The injected AFM panel renders active connections, queue depth, request and token counters, finish reasons, decode-rate history, and latency/size histograms. Histogram percentiles are derived in the browser from Prometheus cumulative buckets. The panel does not poll until opened, remains alongside the chat, and closes with its button or Escape when focus is outside a text field.
For durable monitoring, scrape GET /metrics directly with Prometheus or another compatible collector. The panel is an operator view, not a metrics database.
Model selection is routing, not hot loading
Gateway discovery refreshes in the background, and the WebUI refreshes its model cache periodically. Foundation Models is selected automatically when a multi-model gateway first opens without a saved selection.
Attachments and modality
| Server | Images/PDFs in WebUI | What to do |
|---|---|---|
| Foundation Models | Available when the installed Apple framework supports the request. | Start with afm -w. |
| MLX text model | Not meaningful; the checkpoint has no media encoder. | Choose a VLM and add --vlm. |
| MLX VLM | Supported through multimodal chat parts. | afm mlx -m <vision-model> --vlm -w. |
| DwarfStar DeepSeek V4 | Rejected. | Use text only or switch to an MLX VLM. See DwarfStar + DeepSeek V4. |
Security and network exposure
The WebUI and ordinary API routes do not add authentication. Keep the default loopback hostname for a personal machine. If you bind to 0.0.0.0, both the browser interface and API become reachable from the network unless a firewall or authenticated reverse proxy blocks them.
# Personal, local-only interface
afm mlx -m <model> --hostname 127.0.0.1 -w
# Network binding: add your own authenticated boundary first
afm mlx -m <model> --hostname 0.0.0.0 -wTroubleshooting
| Symptom | Cause | Resolution |
|---|---|---|
| “WebUI enabled but not found” | The compressed bundle is absent from the executable resources and known install locations. | For a source checkout, run the complete build flow; packaged Homebrew and pip releases should already include it. |
| Browser did not open | macOS rejected or could not complete automatic launch. | Open the URL printed by AFM manually. |
| Attachment fails | The selected model is text-only or the runtime does not accept media. | Use a compatible VLM or Foundation Models; DwarfStar cannot accept media. |
| Model picker changes but behavior does not | A single-model process cannot hot-swap via WebUI compatibility calls. | Restart AFM with the intended checkpoint, or use gateway mode for external backends. |
| Metrics panel is empty | No requests have populated counters yet, or /metrics is unreachable. | Send one chat request, then check curl http://127.0.0.1:9999/metrics. |