Donkie
1b1dbbb78f
allow_origins=["*"] with allow_credentials=True makes Starlette echo the caller's origin back and set Access-Control-Allow-Credentials, which tells the browser it may send cookies to whichever site asked. Spoolman has no cookies of its own, so this looked harmless, but plenty of instances sit behind a reverse proxy that does the authentication with one -- and there it let any website the user visited make authenticated requests as them. Now credentials are refused whenever the resolved origin list contains "*" (todo.md task 5). Adds a README Security section. The README has no configuration reference at all -- that lives in the Wiki -- so rather than starting one, this documents the things a user has to know before deciding where to run Spoolman: that there is no authentication by design, that it belongs behind an authenticating reverse proxy if it is reachable beyond the LAN, what SPOOLMAN_CORS_ORIGIN is for, why "*" is a bad idea on a shared network, and that a reverse proxy needs to forward the original Host. Verified with SPOOLMAN_CORS_ORIGIN=* against a real server: the response now carries `access-control-allow-origin: *` and no credentials header, where the audit saw the caller's origin echoed with credentials allowed.
Keep track of your inventory of 3D-printer filament spools.
Spoolman is a self-hosted web service designed to help you efficiently manage your 3D printer filament spools and monitor their usage. It acts as a centralized database that seamlessly integrates with popular 3D printing software like OctoPrint and Klipper/Moonraker. When connected, it automatically updates spool weights as printing progresses, giving you real-time insights into filament usage.
Features
- Filament Management: Keep comprehensive records of filament types, manufacturers, and individual spools.
- API Integration: The REST API allows easy integration with other software, facilitating automated workflows and data exchange.
- Real-Time Updates: Stay informed with live spool updates through Websockets, providing immediate feedback during printing operations.
- Central Filament Database: A community-supported database of manufacturers and filaments simplify adding new spools to your inventory. Contribute by heading to SpoolmanDB.
- Web-Based Client: Spoolman includes a built-in web client that lets you manage data effortlessly:
- View, create, edit, and delete filament data.
- Add custom fields to tailor information to your specific needs.
- Print labels with QR codes for easy spool identification and tracking.
- Contribute to its translation into 18 languages via Weblate.
- Database Support: SQLite, PostgreSQL, MySQL, and CockroachDB.
- Multi-Printer Management: Handles spool updates from several printers simultaneously.
- Advanced Monitoring: Integrate with Prometheus for detailed historical analysis of filament usage, helping you track and optimize your printing processes. See the Wiki for instructions on how to set it up.
Spoolman integrates with:
- Moonraker and most front-ends (Fluidd, KlipperScreen, Mainsail, ...)
- OctoPrint
- OctoEverywhere
- Home Assistant
- MCP Server - Manage your filament inventory through AI assistants like Claude using the Model Context Protocol
Web client preview:
Security
Spoolman has no authentication. This is by design — it is built to sit on a trusted home network alongside your printers, where requiring a login for every Moonraker or OctoPrint call would only get in the way. It does mean that anyone who can reach Spoolman over the network can read and modify your entire inventory.
If your instance is reachable from beyond your own LAN, put it behind a reverse proxy that handles authentication (Authelia, Authentik, or your proxy's own basic auth). Do not forward a port to it directly.
Spoolman does defend the one boundary a browser can be tricked into crossing on your behalf: a website you visit cannot make your browser write to your Spoolman instance, or open a websocket to it, unless it is an origin you have allowed. That protection is not a substitute for the above — it does nothing about anyone already on your network.
SPOOLMAN_CORS_ORIGIN
A comma-separated list of extra browser origins allowed to talk to Spoolman, for example
https://fluidd.local,https://mainsail.local. Leave it unset unless you have a browser-based
client on a different origin; the built-in web client does not need it, and neither does
Moonraker, OctoPrint, Home Assistant or anything else that is not a browser.
Warning
Setting it to
*turns the origin checks off entirely, which means any website you happen to visit can read and modify your Spoolman data in the background. Only do this on a network you trust completely, and list the origins you actually need instead wherever you can. Debug mode (SPOOLMAN_DEBUG_MODE) has the same effect and is not meant for normal use.
If you run Spoolman behind a reverse proxy, forward the original host — nginx
proxy_set_header Host $host;, Apache ProxyPreserveHost On, or the X-Forwarded-Host header,
any of which is enough. Traefik, Caddy and HAProxy do this by default.
Installation
Please see the Installation page on the Wiki for details how to install Spoolman.