Moonraker, Mainsail, and Fluidd: Choosing and Configuring Your Klipper Web Interface

Installing Klipper gets your printer talking a faster, smarter firmware language, but Klipper itself has no web front end — it's a background service that expects a host application to hand it G-code and configuration commands. That's where Moonraker, Mainsail, and Fluidd come in. Moonraker is the API server that bridges Klipper to the outside world, and Mainsail or Fluidd are the browser dashboards that sit on top of it. Nearly every Klipper guide assumes you already have this stack running, but the actual decision of which UI to run, how Moonraker fits in, and how to configure update managers and camera feeds correctly is rarely covered on its own. This guide walks through the full stack from a clean Klipper install to a working, securely reachable dashboard.

How the Pieces Fit Together

It helps to think of the stack in three layers. Klipper itself runs as klippy, a Python process that talks to your printer's microcontroller(s) over serial or CAN and executes the actual motion planning. Moonraker is a separate always-on service that exposes a JSON-RPC and REST API over HTTP and websockets, handles file management, macros, update tracking, and power control, and acts as the single point of contact for any web UI. Mainsail and Fluidd are static single-page web applications — they don't talk to Klipper directly at all, only to Moonraker's API. This separation is why you can run Mainsail and Fluidd side by side on the same Moonraker instance, or swap between them, without touching your printer.conf.

ComponentRoleRuns Where Klipper (klippy)Motion planning, kinematics, executes G-codeHost (Pi/SBC) + MCU firmware MoonrakerAPI server: file access, macros, updates, webcam proxying, power devicesHost, alongside klippy Mainsail / FluiddBrowser dashboard consuming Moonraker's APIServed by nginx on the host, rendered in your browser

Installing the Stack with KIAUH

The Klipper Install And Update Helper (KIAUH) is the standard way to bring up this stack on Raspberry Pi OS, DietPi, or Debian/Ubuntu. It's a menu-driven bash script that installs and updates Klipper, Moonraker, and your chosen UI without you hand-editing systemd units.

Flash Raspberry Pi OS Lite (64-bit) and enable SSH, or use an existing Klipper-capable SBC.
Clone KIAUH: git clone https://github.com/dw-0/kiauh.git then cd kiauh && ./kiauh.sh.
From the menu, install Klipper first, then Moonraker, then your UI of choice (Mainsail, Fluidd, or both).
KIAUH will prompt for the number of printer instances — say 1 unless you're running a multi-printer host.
Once installed, browse to http://<pi-ip> (Mainsail defaults to port 80, Fluidd also defaults to 80 but KIAUH will offer to put a second UI on a different port like 81 if both are installed).

If you'd rather avoid a generic Pi OS image entirely, MainsailOS and FluiddPi are pre-built SD card images that ship Klipper, Moonraker, and their respective UI already configured — a reasonable shortcut if you're setting up a dedicated printer host and don't need anything else on that SBC.

Mainsail vs Fluidd: What Actually Differs

Since both are thin clients over the same Moonraker API, the differences are almost entirely about layout philosophy and a handful of built-in features, not capability.

AspectMainsailFluidd LayoutFixed dashboard with card-based panelsFully customizable, draggable/resizable panel layout Macro editingView and run macros; edit via config fileSame, slightly more exposed macro parameter UI History/analyticsBuilt-in print history and job statsBuilt-in print history, plus per-job thumbnails ThemingLight/dark, a few accent colorsLight/dark, more granular per-panel theming Mobile useResponsive, works but dashboard cards stack awkwardly on small screensGenerally considered the stronger mobile/tablet experience Update channel maturityVery widely deployed, the de facto default in most guidesSlightly smaller install base, actively maintained

There's no wrong choice — both consume the exact same moonraker.conf and printer.cfg, so trying one, disliking it, and switching to the other via KIAUH costs you nothing but a few minutes. Many multi-printer shops run Fluidd for a tablet mounted at the printer and Mainsail on a desktop monitor, purely on layout preference.

Moonraker Configuration Essentials

Moonraker's behavior lives in moonraker.conf, usually at ~/printer_data/config/moonraker.conf. A few sections matter more than the defaults KIAUH generates:

[authorization] — sets which IP ranges and CORS origins can reach the API without a key. Leave your LAN range in trusted_clients but do not add 0.0.0.0/0 if you plan to expose the interface beyond your LAN.
[update_manager] — tracks git-based updates for Klipper, Moonraker, and any registered UI or plugin (KlipperScreen, crowsnest, etc.) so the "machine" tab in your UI shows real update status instead of nothing.
[power <name>] — integrates smart plugs (Tasmota, Shelly, generic GPIO relay) so the dashboard can power-cycle the printer or a bed light directly, and optionally auto-power-off after a completed print.
[octoprint_compat] — a compatibility shim that makes Moonraker answer OctoPrint's API endpoints, which is what lets slicers with "upload and print via OctoPrint" plugins (like some Cura and PrusaSlicer setups) work against a Klipper/Moonraker host without modification.

Adding Camera Streaming

Both UIs can embed a live camera feed, but the feed itself is served by a separate piece: crowsnest (the modern replacement for the older mjpg-streamer setup), also installable via KIAUH. Once crowsnest is configured with your USB or Pi Camera Module device path, add the matching webcam entry in Moonraker's [webcams] config (or through the UI's webcam settings panel, which writes the same config) and the live view appears directly on the dashboard alongside print progress and temperature graphs.

Remote Access Without Exposing Your Printer to the Internet

Port-forwarding a printer dashboard directly to the internet is a common and risky shortcut — Moonraker's API can start prints, run arbitrary macros, and in some configurations execute shell commands, so an exposed instance is a real attack surface, not just an inconvenience if found. Prefer one of these instead:

Tailscale or WireGuard — put the Pi on your personal mesh VPN and reach it exactly as if you were on your home LAN, from anywhere.
Obico or a similar cloud relay — a purpose-built remote monitoring service that only relays camera and status data outward, without exposing the control API.
A reverse proxy with authentication — if you must expose something, put nginx or Caddy in front with HTTP basic auth or an OAuth proxy, and only forward that, never the raw Moonraker port.

Troubleshooting Common First-Setup Problems

SymptomLikely CauseFix Dashboard loads but shows "Klipper disconnected"klippy not running, or wrong serial path in printer.cfgCheck ls /dev/serial/by-id/ and match the MCU serial line; restart the klipper service Webcam panel is blankcrowsnest not installed or wrong device indexVerify crowsnest.conf device path and restart the crowsnest service "Unauthorized" API errors from a slicer pluginoctoprint_compat missing or API key mismatchEnable [octoprint_compat] in moonraker.conf and re-generate the API key in the UI's settings Update manager shows nothing to update[update_manager] entries missing for that componentAdd explicit update_manager sections per KIAUH's generated template

Once this stack is running, it becomes the foundation almost every other Klipper feature builds on — input shaper calibration graphs, Spoolman filament tracking, and KlipperScreen all assume a working Moonraker instance underneath them. Getting this layer right the first time, especially the authorization and remote-access choices, saves a lot of retrofitting later.

Related Guides

Loading_