Klipper Moonraker and Fluidd/Mainsail Setup for Voron

Klipper Firmware Setup

Klipper is the firmware that powers most Voron printers, but the user interface you actually interact with is a separate layer: Moonraker provides the API backend, and a web frontend (Fluidd or Mainsail) gives you the graphical interface. Setting these up correctly is essential for a smooth Voron experience. This guide covers everything from initial installation through remote access, plugins, and troubleshooting. Last updated: May 2025.

Whether you're building a new Voron from scratch or upgrading an existing printer from OctoPrint to the Klipper ecosystem, this guide walks you through each step. We use KIAUH (Klipper Installation And Update Helper) as the recommended installation method, cover the key configuration options in moonraker.conf, compare Fluidd vs Mainsail, and show you how to add plugins for filament management, spaghetti detection, and more.

Moonraker Overview — What It Does

Moonraker is a Python-based API server that acts as the bridge between Klipper firmware and the web frontend. It runs as a systemd service on your Raspberry Pi (or CB1, or any Linux host) and provides a JSON-RPC API that web interfaces like Fluidd and Mainsail use to communicate with Klipper.

Moonraker does a lot more than just relay commands:

• Klipper communication: Talks to Klipper via its UNIX socket, translating between Klipper's internal commands and the web frontend's API requests.
• File management: Manages G-code files on the Raspberry Pi's filesystem, handles uploads, directory organization, and file operations. Can be configured to manage multiple printer configurations and firmware files.
• Update manager: Provides automatic or manual updates for Klipper, Moonraker, the web frontend, and system packages through a unified interface. This is one of Moonraker's killer features — one-click updates for your entire printer software stack.
• Authorization and security: Manages trusted clients, API keys, CORS domains, and authentication for web access. Essential for remote access security.
• Database and history: Maintains a SQLite database of print history, job queue, and system statistics. The history tab in Fluidd/Mainsail uses this data.
• WebSocket and file streaming: Provides real-time WebSocket connections for live status updates, and streams G-code files to Klipper during printing.
• Plugin system: Supports third-party plugins that extend functionality (more on this below).

Fluidd vs Mainsail — Which Frontend to Choose

Both Fluidd and Mainsail are modern web interfaces built on Vue.js that run in your browser and communicate with Moonraker. They look similar and share many features, but there are key differences:

Our recommendation: Start with Mainsail. It has more features, a more polished mobile experience, and the drag-and-drop dashboard makes it easy to set up exactly the layout you want. However, if you're running on a Pi Zero or very memory-constrained hardware, Fluidd's lighter footprint may be the better choice. Both are excellent — you can't go wrong with either. You can even install both and switch between them while configuring, then remove the one you don't use.

Installation via KIAUH (Recommended)

KIAUH (Klipper Installation And Update Helper) is the standard tool for installing and managing Klipper, Moonraker, and web interfaces on Raspberry Pi and similar single-board computers. It's a bash script that automates the entire setup process.

Prerequisites

• A Raspberry Pi 3B+, 4B, 5, or CB1 running Raspberry Pi OS Lite (64-bit recommended) or any Debian-based distro
• Klipper already installed and configured for your Voron (see our Klipper Setup Guide)
• Python 3.8+ (pre-installed on Pi OS)
• Git (sudo apt install git -y)
• An internet connection on the Pi

KIAUH Installation Steps

1. Download KIAUH:

   cd ~
   git clone https://github.com/dw-0/kiauh.git
   cd kiauh
   chmod +x kiauh.sh
   ./kiauh.sh

2. Select installation option: KIAUH launches a menu-based interface. Type "1" for "Install" to enter the installation menu.
3. Select components to install: Use the spacebar to select:
   • [x] Klipper (already installed — skip if present)
   • [x] Moonraker
   • [x] Mainsail (or Fluidd — or both)
   Press Enter to confirm.
4. Configure Moonraker: KIAUH will ask for:
   • Instance name: Leave as "printer" or set a custom name if running multiple instances.
   • Klipper Unix socket path: Default is /tmp/klippy_uds. Leave as default unless you have a custom Klipper config.
   • Config directory: Default is ~/printer_data/config. Accept the default.
   • Log directory: Default is ~/printer_data/logs. Accept the default.
5. Install nginx: KIAUH will install and configure nginx as a reverse proxy for the web interface. This is handled automatically — you don't need to configure nginx manually unless you want custom domains or SSL.
6. Complete installation: KIAUH will download and install all components, configure systemd services, and start them. After completion, your web interface should be accessible at http://<your-pi-ip>/ or http://<your-pi-ip>:80.

Manual Installation (Without KIAUH)

If you prefer to install manually (useful for custom setups or troubleshooting), the basic steps are:

1. Clone the Moonraker repository: git clone https://github.com/Arksine/moonraker.git ~/moonraker
2. Run the install script: cd ~/moonraker && ./scripts/install-moonraker.sh
3. Clone your chosen frontend: git clone https://github.com/mainsail-crew/mainsail.git ~/mainsail or git clone https://github.com/fluidd-core/fluidd.git ~/fluidd
4. Configure nginx to serve the frontend from its build directory. Sample nginx configs are provided in each frontend's repository.
5. Copy and customize moonraker.conf from the Moonraker repository's docs/example-moonraker.conf.

Manual installation gives you more control but is significantly more error-prone. Use KIAUH unless you have a specific reason not to.

Key Moonraker Configuration

Moonraker's configuration file lives at ~/printer_data/config/moonraker.conf (or ~/klipper_config/moonraker.conf on older setups). Here are the most important sections:

[authorization] — Security Settings

[authorization]
# Enable API key authentication
api_key_file: ~/printer_data/config/api_key.txt
# List of CORS domains allowed to access Moonraker
cors_domains:
    http://*.local
    http://192.168.*
# Trusted IPs that bypass authentication
trusted_clients:
    127.0.0.1
    192.168.1.0/24
# Force HTTPS for all external connections (requires SSL certificate)
force_logout: false

trusted_clients is important for local network access. Add your local subnet (e.g., 192.168.1.0/24) so devices on your LAN can access the web interface without entering a password every time. cors_domains must include any domains from which you'll access Moonraker — if you're using a reverse proxy or custom domain, add it here.

[file_manager] — File System Access

[file_manager]
# Enable file upload and management
enable_object_processing: True
# Path to the config directory
config_path: ~/printer_data/config
# Path to the G-code directory
log_path: ~/printer_data/logs
# Additional file paths that can be accessed
enable_multi_mcu_firmware: True
firmware_path: ~/printer_data/firmware_binaries

The enable_multi_mcu_firmware option lets you store Klipper firmware binaries for multiple MCU configurations (e.g., mainboard + toolhead board + accelerometer). Moonraker can upload the correct binary to each MCU during firmware update. The firmware_path directory is where KIAUH stores compiled firmware binaries.

[update_manager] — Automatic Updates

[update_manager]
# Enable automatic updates
enable_auto: False            ; Set True to auto-update (not recommended for production)
channel: dev                  ; Options: dev, beta, stable
# Refresh interval in hours
refresh_interval: 24

[update_manager klipper]
type: git_repo
path: ~/klipper
origin: https://github.com/Klipper3d/klipper.git
manage_python: True
requirements: ~/klipper/scripts/klippy-requirements.txt
install_script: ~/klipper/scripts/install-ubuntu-22.04.sh
is_system_service: True

[update_manager moonraker]
type: git_repo
path: ~/moonraker
origin: https://github.com/Arksine/moonraker.git
manage_python: True
requirements: ~/moonraker/requirements.txt
install_script: ~/moonraker/scripts/install-moonraker.sh
is_system_service: True

[update_manager mainsail]
type: web
channel: stable
repo: mowad/mainsail
path: ~/mainsail

The update manager checks each configured component for updates and presents them in the web UI. You can update with one click in Fluidd/Mainsail's "Machine" tab. We recommend keeping enable_auto: False — review update notes before applying, as occasionally updates introduce breaking changes.

Useful Moonraker Plugins

Obico (Spaghetti Detection)

Obico is an AI-powered print failure detection system that uses a webcam feed to identify common print failures: spaghetti, layer shifts, blobs, and complete print detachment. When a failure is detected, it can pause the print, send a notification to your phone, and optionally cancel the print.

Installation: sign up at obico.io, install the Obico plugin via KIAUH (it's in the KIAUH plugin menu under "Extension 3"), or manually add the Moonraker plugin. Configure your webcam in Moonraker's [webcam] section. The free tier covers one printer with basic detection; the paid tier adds multiple cameras, faster AI processing, and unlimited printers. For Voron owners printing expensive ABS parts, this is cheap insurance against failed overnight prints.

G-Code Shell Command

This plugin allows you to execute arbitrary shell commands on the Raspberry Pi directly from G-code macros. Use cases: run a script to upload print data to a spreadsheet, trigger a notification via ntfy.sh, reboot the Pi from a macro, or run a custom camera timelapse script.

Installation: clone the repository to ~/moonraker-plugins and add the plugin to moonraker.conf. Example usage in a macro:

[gcode_shell_command notify_print_done]
command: curl -d "Voron print complete on printer1" ntfy.sh/voron_alerts
timeout: 2.
verbose: True

[gcode_macro PRINT_END]
gcode:
    # ... existing PRINT_END code ...
    RUN_SHELL_COMMAND CMD=notify_print_done

This sends a push notification to your phone via ntfy.sh whenever a print finishes. The possibilities are endless — be creative but cautious: shell commands run as the Pi user and have full system access.

Spoolman (Filament Inventory Management)

Spoolman is a lightweight web service that tracks your filament spools: material, color, brand, weight remaining, and usage history. The Moonraker Spoolman plugin integrates this into Fluidd/Mainsail, automatically deducting filament usage from the active spool during printing.

Installation: install Spoolman (Docker or Python), then add the plugin to Moonraker. In your PRINT_START macro, add SET_ACTIVE_SPOOL ID=<spool_id> to associate a print with a spool. The web interface shows remaining filament and estimated spool life. Essential if you have more than 3-4 spools and want to track what's left without weighing each one.

Remote Access — Getting to Your Voron from Anywhere

Accessing your Voron's web interface from outside your local network is convenient but requires careful security. Here are the options, ordered from safest to least safe:

Tailscale (Recommended)

Tailscale creates a wireguard-based mesh VPN that connects all your devices (phone, laptop, desktop, Raspberry Pi) into a secure virtual network. Install Tailscale on your Raspberry Pi and on every device you want to access Moonraker from. Then access the web interface at http://<pi-tailscale-ip>/ from anywhere in the world, with full encryption and no open ports on your home router.

Installation on Pi: curl -fsSL https://tailscale.com/install.sh | sh, then sudo tailscale up. Authenticate via the URL displayed. That's it — Tailscale handles all the networking. On your phone, install the Tailscale app and connect. Moonraker will be accessible at the Pi's Tailscale IP address. Tailscale's free tier covers up to 3 users and 100 devices, which is enough for most Voron owners.

WireGuard (Self-Hosted VPN)

If you prefer not to rely on a third-party service, set up your own WireGuard VPN server (on a Raspberry Pi, VPS, or home server) and configure your devices to connect through it. This is more complex to set up than Tailscale but gives you full control. Many Voron owners run WireGuard on their home router (pfSense, OPNsense, or OpenWrt) and connect their phone/laptop to it when away from home.

Moonraker's Built-in Proxy (Moonraker-trusted Proxy Mode)

Moonraker includes a lightweight HTTP proxy that can serve the web frontend over port 7125. Combined with a dynamic DNS service, this allows direct access to your printer. However, this exposes Moonraker directly to the internet if you forward port 7125 — not recommended. If you use this method, put an nginx reverse proxy in front with HTTPS and strong authentication.

Port Forwarding (Not Recommended)

Forwarding ports (80, 443, or 7125) from your home router to the Raspberry Pi exposes your printer to the open internet. Even with Moonraker's API key authentication, this is risky: unpatched vulnerabilities in Moonraker, nginx, or the web frontend could be exploited. The Voron community has seen cases of printers being accessed by unauthorized users. Use a VPN instead.

Mobile Apps

• Mobileraker (iOS / Android): The most popular native mobile app for Moonraker. Provides live camera feed, print status, temperature graphs, and the ability to start/stop prints. Supports multiple printers and push notifications for print completions or failures. Premium version ($2.99) adds widgets and Apple Watch support. Highly recommended.
• G-Code View for iPhone: A lightweight iOS app that provides a simple interface for viewing G-code files, monitoring print progress, and checking temperatures. Less feature-rich than Mobileraker but free and fast. Good as a quick-status checker.
• Mainsail Mobile (PWA): Mainsail's built-in Progressive Web App support means you can "install" the web interface on your phone's home screen. It caches assets and provides a full-screen experience with touch controls. Works well on recent browsers. No app store download needed.

Troubleshooting

WebUI Not Loading (Blank Page / Connection Refused)

• nginx not running: Check with sudo systemctl status nginx. If stopped: sudo systemctl restart nginx. Check nginx error logs at /var/log/nginx/error.log.
• Wrong port or IP: The web interface serves on port 80 (HTTP) or 443 (HTTPS). Ensure you're connecting to http://<pi-ip>:80 or just http://<pi-ip>. Some setups use port 7125 for Moonraker direct access — try that if port 80 fails.
• Firewall blocking: Check if ufw or iptables is blocking port 80: sudo ufw status. Allow port 80: sudo ufw allow 80.
• Browser cache: Hard-reload (Ctrl+Shift+R) or clear browser cache. Fluidd/Mainsail caches assets aggressively — an old cached version may not connect to the updated Moonraker API.

Moonraker Cannot Connect to Klipper

• Klipper not running: Check with sudo systemctl status klipper. Restart: sudo systemctl restart klipper.
• Socket path mismatch: Verify that the klippy_uds_address in moonraker.conf matches the actual path. Default is /tmp/klippy_uds. Check that this file exists: ls -la /tmp/klippy_uds. If it doesn't exist, Klipper isn't running or has a different socket path configured.
• Moonraker not running: sudo systemctl status moonraker. Logs at ~/printer_data/logs/moonraker.log. The log usually indicates exactly what's wrong — check the last 50 lines.
• Permission denied: The Moonraker user may not have permission to read the Klipper socket. Ensure both services run as the same user (typically pi or klipper). Check ps aux | grep moonraker to see which user Moonraker is running as.

nginx 502 Bad Gateway

A 502 error means nginx can't reach the backend service (Moonraker or the static file server). Causes:

• Moonraker not running: Check Moonraker status as above.
• Incorrect nginx proxy_pass: Your nginx config may be pointing to the wrong port. The default nginx config for Mainsail/Fluidd proxies API calls to http://localhost:7125. Verify this is correct in /etc/nginx/sites-available/mainsail or fluidd.
• Web frontend files not found: Ensure the frontend build files exist at the path nginx expects. For Mainsail: ls ~/mainsail/dist should show the built files. If empty, run cd ~/mainsail && git pull to rebuild.

Permission Issues with File Uploads or Config Editing

• Moonraker cannot write to config directory: Add the Moonraker user to the same group as the config directory: sudo usermod -a -G pi moonraker (or whatever group owns ~/printer_data). Then restart Moonraker.
• Git ownership issues: If you run git pull manually in the Klipper or Moonraker directories, the files may change ownership to root. Fix: sudo chown -R pi:pi ~/klipper ~/moonraker ~/mainsail (replace pi with your username).
• /tmp directory cleared on reboot: Some systems clear /tmp on reboot. If Klipper's socket is in /tmp, add a tmpfiles.d config: echo "d /tmp 1777 root root -" | sudo tee /etc/tmpfiles.d/tmp.conf. The socket is recreated when Klipper starts, so this is usually only an issue if Klipper fails to start after a reboot.

The Moonraker + Fluidd/Mainsail stack is mature and well-tested on Voron builds. Once set up correctly, it's remarkably stable — many users report months of uptime without touching the configuration. Start with KIAUH, add a VPN for remote access, install a plugin or two that solves a problem you actually have, and you'll have a professional-quality printer control system that rivals anything in the commercial 3D printing world.