First Boot

After successful flash there are couple steps to take, to finish your install.

Initial boot

After MainsailOS is successfully written to the SD card, please insert the card into your device. Connect necessary peripherals such as network cables, webcams, the USB cable to your 3D printer. Then turn on the device and let it boot up.

The first start of MainsailOS will take some time to expand your file system. The larger the SD card, the longer the first start-up process will take.

Raspberry PI: The green LED indicates SD card activity. As soon as it only flashes occasionally, the process should be completed.

This process can take up to 5 minutes to complete on slower models such as the Pi Zero 2 and Pi 3 series.

Access Mainsail

As soon as the boot process is finished, Mainsail should be available at http://mainsailos.local or http://mainsailos. Replace "mainsailos" with the hostname you may have set when you flashed the image.

In the case that this does not work, you can also try to access Mainsail directly with the IP address of the device. To do this, you have to look up its IP address in your router.


We recommend to update the system to the current version.

Even though we regularly release new versions of the OS, we cannot guarantee that all components (System, Klipper, Moonraker, Mainsail) are up to date at the moment you install the system.

When you open the Update Manager the first time, you will see something like this:

These errors are typical because Moonraker (the Update manager is a component of Moonraker) hasn't checked it until now. Just click on the blue "Refresh" button on the top right to check for updates.

Now the Update Manager should show all available updates. Click the "Update all components" button and wait a few minutes to install all updates. You can find more information about the Update Manager in the Mainsail documentation.


You will be presented with a few warnings because Mainsail requires some settings in Klipper's printer.cfg. For more information, please take a look at Mainsail's configuration page.

These settings are already available in the form of the mainsail.cfg file and only need to be included in the Klipper config. This is a simple step and can be done from Mainsail's file manager.

To get to Mainsail's file manager, click on "Machine" in the navigation bar. There you will find mainsail.cfg and printer.cfg. Open the editor by clicking on those files.

We recommend checking mainsail.cfg and adapting it to your needs. Then open the printer.cfg and type in the editor [include mainsail.cfg] and click on "SAVE & RESTART".

After that, the warnings should disappear.

Congratulations! Mainsail is now generally ready for operation. However, you still need a Klipper configuration for your 3D printer. Either you already have it, in which case you can upload it via the File Manager, or you have to create your own.

Last updated