MainsailOS

MainsailOS is a pre-configured operating system for your 3D printer's single-board computer (SBC). It simplifies getting started with Klipper and the Mainsail web interface by providing everything you need in one ready-to-use package.

Our images are built on stable, well-supported distributions:

• Raspberry Pi: Based on the official Raspberry Pi OS.
• Other SBCs: Based on Armbian or vendor-specific OS builds (e.g., OrangePiOS).

All images come with the necessary software pre-installed and configured, so you can focus on printing. For a complete list of what's included, see the Features & Components section below.

Documentation

For detailed installation and setup guides, please visit our official documentation:

docs-os.mainsail.xyz

Community & Support

Have questions or need help with your setup? Join our active community on Discord!

Mainsail Discord Server

Features & Components

MainsailOS comes ready to use with a complete software stack and several key configurations designed to streamline your setup process.

Core Software Stack

• Klipper: The core 3D printer firmware.
• Moonraker: The API server for Klipper.
• Mainsail: Our modern web interface for Klipper.
• Crowsnest: A simple and effective webcam streamer wrapper.
• Sonar: A keepalive daemon to ensure WiFi stability.
• Nginx: A high-performance web server and reverse proxy to provide Mainsail and proxy the API.

Key Configurations & Conveniences

• Ready-to-use UART: The serial connection is enabled by default, allowing you to directly connect your printer board without a USB cable.
• Input Shaper Ready: All required Python dependencies for Klipper's Input Shaper are pre-installed, saving you setup time and letting you start tuning right away.
• Katapult Support: The python3-serial package is included, which is a necessary dependency for flashing firmware via Katapult (formerly CanBoot).

Support the Mainsail-Crew

MainsailOS is a passion project developed and maintained by the Mainsail Crew. We dedicate a significant amount of our free time, almost daily, to keep the project alive and moving forward.

Your support directly fuels our development efforts. Donations help us cover essential costs for hardware, such as new SBCs and SD cards, which are crucial for testing, developing new features, and expanding board compatibility.

If you find MainsailOS useful, please consider supporting our work. Every contribution, no matter the size, makes a real difference.

• GitHub Sponsors
• Patreon
• Ko-Fi

Building & Development

We've streamlined the build process, allowing you to create your own custom MainsailOS image without needing a complex local development environment.

How it Works

1. Fork this repository.
2. Customize your settings or add your own modules.
3. Push your changes to your fork.

Our GitHub Actions workflow will then automatically handle the rest.

Build Outcomes

• On every push: A new image is built and uploaded as a workflow artifact, perfect for testing.
• For a new release: Manually trigger the Release action to publish a formal release with your modifications.

Need Help?

If you need guidance on customizing the build process or developing your own modules, feel free to connect with the Crew on our Discord server in the #public-dev-talk channel.