Moonraker Config Guide: moonraker.conf Explained for Klipper

Short answer: Moonraker config lives in moonraker.conf: by default ~/moonraker.conf, or ~/printer_data/config/moonraker.conf on MainsailOS and FluiddPi images. The only required section is [server]. Most setups also need [authorization] so your network and web interface can reach the API, and [octoprint_compat] so slicers can upload files.

Moonraker is the API server that sits between Klipper and everything that talks to it: the Fluidd or Mainsail web interface, your slicer and remote tools. It serves HTTP and talks to Klippy, Klipper's host process, over a Unix domain socket. This guide walks through the Moonraker config sections you are most likely to touch, with working examples taken from the official Moonraker documentation, and then covers what changes when you run more than a couple of Klipper printers.

Where is moonraker.conf?

By default Moonraker loads its configuration from ~/moonraker.conf. Prebuilt images such as MainsailOS and FluiddPi load it from ~/printer_data/config/moonraker.conf instead. After any change, restart Moonraker for it to take effect.

The [server] section

[server] is the only required section. It sets where Moonraker listens and how it reaches Klipper:

[server]
host: 0.0.0.0
port: 7125
klippy_uds_address: /tmp/klippy_uds

• host is the address the HTTP server binds to. The default binds to all IPv4 interfaces.
• port is the port Moonraker listens on. The default is 7125, which is why slicer and tool examples often end in :7125.
• klippy_uds_address is the Unix domain socket used to talk to Klippy. The default is /tmp/klippy_uds. If Moonraker reports that it cannot connect to Klipper, check that this path matches the socket Klipper creates.

The [authorization] section: trusted clients and CORS

This section decides who may use the API. If a web interface loads but shows connection errors, or a slicer upload is refused, this is the first place to look.

[authorization]
trusted_clients:
  192.168.1.30
  192.168.1.0/24
  my-printer.lan
cors_domains:
  http://klipper-printer.local
  http://second-printer.local:7125

• trusted_clients is a newline-separated list of IP addresses, IP ranges or hostnames that get full API access. A range such as 192.168.1.0/24 trusts your whole home or lab subnet. Keep this to your local network: do not trust everything.
• cors_domains enables cross-origin requests from the listed domains. Add an entry when a web interface or tool is served from a different host name or port than Moonraker itself, as in the second example above.

The [octoprint_compat] section: slicer uploads

Slicers such as PrusaSlicer, SuperSlicer and OrcaSlicer upload to Klipper printers through an OctoPrint-style API. Moonraker emulates part of that API when this section is present:

[octoprint_compat]
enable_ufp: True
webcam_enabled: True

An empty [octoprint_compat] header is enough to start. Then, in the slicer, set the host type to OctoPrint (OrcaSlicer calls it Octo/Klipper), enter the printer address such as http://192.168.1.100, add :7125 if needed, and type any non-empty text as the API key, because Moonraker does not validate it. For step-by-step slicer screens, see how to add a printer in OrcaSlicer.

The [file_manager] section

[file_manager]
queue_gcode_uploads: False

If you leave this section out, defaults are used. Setting queue_gcode_uploads: True adds uploaded files to Moonraker's job queue when the upload asks to start printing, instead of starting them at once. That is useful when several people send jobs to one machine.

The [update_manager] and [machine] sections

[update_manager]
enable_auto_refresh: False

[machine]
provider: systemd_dbus

[update_manager] turns on Moonraker's update manager, which handles software updates. Updates only work on clean ("pristine") git repositories, so local edits to Klipper's source will block them. [machine] controls how Moonraker manages system services; the default provider is systemd_dbus.

Fluidd vs Mainsail: which interface?

Both are web interfaces for Klipper that run on top of Moonraker, so the Moonraker config above applies to either one.

• Fluidd describes itself as a lightweight, responsive interface for Klipper, with a G-code viewer, thermal charts, webcam support, a file manager and updates for Klipper, Moonraker and Fluidd.
• Mainsail describes itself as a web interface for managing and controlling Klipper printers. It can be installed with the MainsailOS image, the KIAUH script, Docker or a manual setup.

For a single printer the choice is mostly about taste. Try both: they read the same moonraker.conf, and you can switch later.

Common Moonraker config errors

• The interface says it cannot connect to Moonraker. Check that your computer's address is covered by trusted_clients, and that the page's origin is listed in cors_domains if it is served from another host or port.
• Moonraker cannot reach Klipper. The klippy_uds_address path does not match Klipper's socket.
• The slicer upload fails. [octoprint_compat] is missing, or the slicer is not using port 7125 on a non-standard setup.
• Uploads succeed but nothing prints. Turn on the slicer's "start print after upload" option, or check whether queue_gcode_uploads is sending the job to the queue.

Running many Klipper printers

A web interface is where you control a printer. With five or fifty Klipper machines you also need shared queues, user permissions and one view of every job. That is the job of 3D printer management software.

3DPrinterOS has a generic Moonraker printer type for connecting Moonraker-based printers, with remote printing, cloud slicing and fleet-wide job management. For the Creality K1 series, the 3DPrinterOS help center describes an install script that sets up 3DPrinterOS on the printer and installs Moonraker if it is not detected; see Creality 3D printer software. Klipper printers then sit in the same queues and reports as the rest of the fleet: see Klipper 3D printer software and 3D printer farm management.

Frequently asked questions

Where is the Moonraker config file?

Moonraker loads ~/moonraker.conf by default. Prebuilt images such as MainsailOS and FluiddPi use ~/printer_data/config/moonraker.conf instead.

What port does Moonraker use?

Moonraker listens on port 7125 by default. You can change it with the port option in the [server] section.

How do I let my slicer upload to Moonraker?

Add an [octoprint_compat] section to moonraker.conf and restart Moonraker. In the slicer, choose the OctoPrint host type, enter the printer's address and any non-empty API key, then test the connection.

What does trusted_clients do in Moonraker?

trusted_clients lists the IP addresses, ranges or hostnames that are trusted and given full API access, such as 192.168.1.0/24 for a local subnet.

Do Fluidd and Mainsail need different Moonraker configs?

No. Both are web interfaces that run on top of Moonraker and read the same moonraker.conf. If either is served from a different host or port, add it to cors_domains.

Can 3DPrinterOS manage Klipper printers?

Yes. 3DPrinterOS connects Moonraker-based printers for remote printing, cloud slicing and fleet-wide job management, so Klipper printers share queues and reports with the rest of the fleet.