Work in progress (v0.2.2-wip). It runs and its tests pass, but it has only been run
against a simulated printer and against a real Klipper + Moonraker with a software-only
controller. It has not been run on a physical printer yet. See
what was tested before trusting it with one.
KlipPlug is a plugin host for Klipper printers. It sits next to Mainsail or Fluidd, talks to
Moonraker, and gives you a web page where you install plugins with a click.
Its plugin API uses the same names as OctoPrint's (mixins, hooks, events, the browser client), so
an OctoPrint plugin can often be loaded unchanged, and the ones that cannot are told apart before
you install them. KlipPlug itself needs nothing from OctoPrint and nothing outside the Python
standard library.
What it does
- Runs plugins outside Klipper. Plugins live in separate worker processes. Klipper and Moonraker are never patched and never wait on plugin code.
-
Speaks OctoPrint's plugin API.
import octoprint.plugin,StartupPlugin,SettingsPlugin,SimpleApiPlugin,__plugin_hooks__,self._printer.commands(...), Knockout view models and Jinja2 templates all work, backed by KlipPlug's own code. The full table says what is native, emulated, partial or unsupported. - Checks a plugin before installing it. The scanner reads the source (it never runs it) and gives one of four verdicts: runs natively, runs with limits, needs the OctoPrint kernel, or cannot work on Klipper.
- Detects stalls and crashes. A plugin that hangs, freezes its process, crashes, or cannot keep up is quarantined, and the page shows which plugin, in which call, and for how long. The other plugins carry on. How it works.
- Optional OctoPrint kernel. For plugins KlipPlug cannot host, one button installs a real OctoPrint 2.0 in its own folder with the unneeded parts switched off, linked to the same Moonraker and watched for stalls. Details.
- Lets Klipper macros call plugins, which OctoPrint cannot do.
Try it in two minutes (no printer needed)
Double-click the launcher for your system and press Try with a simulated printer:
| System | File | Notes |
|---|---|---|
| Linux | KlipPlug-Linux.sh |
Choose "Run" in the file manager. Needs python3; the window needs python3-tk. |
| Windows | KlipPlug-Windows.bat |
Needs Python 3 from python.org. |
| macOS | KlipPlug-Mac.command |
First time: right-click, Open (it is not signed). |
The simulated printer heats up and "prints" a file in about a minute so you can watch events
arrive in the example plugin. No hardware is touched.
Use it with a printer
On the printer's own computer (Raspberry Pi, thin client, anything running Moonraker):
git clone https://github.com/The-Dorkknight/klipplug.git
cd klipplug
./Install-On-Printer.sh
The script finds every Klipper instance, installs a systemd service for each, starts it and then
checks three things before it says it worked: systemd reports the service active, KlipPlug
reports it reached Moonraker, and Moonraker lists KlipPlug as a connected agent. Then open
http://<printer>:7130/.
Built into a card or disk image before it ever boots: image builders can add KlipPlug with
one command; see Adding KlipPlug to an image builder. The
Pi Hotspot Injector (2.4.0 and later)
has it as a tick box on its Build Klipper tab, and the Wyse 3040 Klipper installer (0.2.0-wip
and later) as a tick box on its Build tab.
From another computer: start the launcher, type the printer's Moonraker address
(for example 192.168.1.50:7125) and press Start. Plugins then run on your computer, not on
the printer.
How well do OctoPrint plugins work?
Measured on the 400 plugins of OctoPrint's public plugin registry whose source could be
downloaded on 2026-10-07. Method and caveats.
| Plugins | |
|---|---|
| Scanned | 400 |
| Scanner says: runs natively | 162 |
| Scanner says: runs with limits | 105 |
| Scanner says: needs the OctoPrint kernel | 129 |
| Scanner says: cannot work on Klipper | 4 |
| Tried in KlipPlug (the first two groups) | 267 |
| Loaded and started | 202 |
| ...with no error at start-up or page load | 174 |
| Failed for a missing Python package (mostly Raspberry Pi GPIO libraries, absent on the test machine) | 60 |
| Failed for another reason | 5 |
"Loaded" means the plugin imported, initialised and started inside a KlipPlug worker and its
browser code mounted. It does not mean every feature of the plugin works: only a handful were
exercised by hand.
Two things no host can fix under Klipper:
- Klipper prints files itself, so nothing can watch or rewrite each line as it is sent. The G-code hooks therefore only see commands that go through KlipPlug.
- Plugins that send Marlin-only G-code (
M500,G29,M851...) need matching Klipper macros. The scanner lists them.
For plugin developers
- Porting an OctoPrint plugin
- Hook, mixin and event standard
- Example plugin
- Architecture
- Licence notes, including what it means for plugins
Footprint
Measured on a 2-core x86 machine, connected to a real Klipper + Moonraker, five plugins loaded,
idle: core process about 40 MB, plugin worker about 19 MB, 0.2 % of one CPU core. A stock
OctoPrint 2.0 development snapshot measured on the same machine used 110 to 138 MB. Not yet
measured on a Raspberry Pi.
Known limits
- Not run on a physical printer, on a Raspberry Pi, on Windows or on macOS.
-
Install-On-Printer.shcould only be dry-run: the test machine had no systemd. The image-builder install was run in a chroot on a PC, not on a Raspberry Pi card. - No user accounts. Anyone on a trusted network address can install plugins, which means running code. Read Security before exposing the port.
- Plugins are isolated for stability, not for security. A plugin can do whatever its user can.
-
filesViewModeland several other OctoPrint view models have no stand-in; plugins needing them are sent to the kernel. - Plugin self-update, file preprocessors and the graphical hardware manager are not built yet.
Artwork
The picture shows an orange 3D-printed test boat covered in mains sockets. The boat is meant to
be an OpenVessel
(by Lite on Printables), the open test-print boat that is not a Benchy. The picture itself is a
render, so it is not a faithful copy of that model. Printables lists no open licence for
OpenVessel beyond its own site terms, so check with the author before reusing the artwork
elsewhere. KlipPlug is not affiliated with OpenVessel or its author.
Related work
Nothing equivalent existed when this was started; the survey lists what
was found, and the research notes record the questions asked on the
way and the measurements behind the design.
Top comments (1)
tr.ee/dev-to