mirror of
https://github.com/maziggy/bambuddy.git
synced 2026-10-03 12:46:49 +02:00
MartinNYHC
e2e66e14b7
**Bambuddy 0.2.4.7** **⚠ Upgrade Notes — Read Before Updating** 0.2.4.7 is a fix-led patch release on the same 0.2.4 code base — no schema breaks beyond auto-migrated column additions (dialect-branched for SQLite and Postgres), no Docker entrypoint changes. The in-app Apply Update button in Settings → System → Updates works for Docker and for any native install already on 0.2.4.x. Four behavior-change callouts to know about before you upgrade: - Capture-Finish-Photo on the printer side is no longer force-toggled at dispatch (#1721, reported by @agrisci). The earlier workaround force-enabled the printer-side setting on every print to drive the finish-photo capture; the side effect was that intermediary progress notifications fell silent on A1, and the slicer's own Capture Finish Photo checkbox was silently overridden. Dispatch no longer flips the printer-side setting. Finish-photo capture is now driven by Bambuddy's own stage-22 pre-capture path with a FINISH-state fallback. If you previously unchecked Capture Finish Photo in the slicer to dodge the side effect, you can re-enable it. If you relied on the force-on to get finish photos without slicer changes, the FINISH-state fallback covers it — no UI change required. - Slicer Bundle (.bbscfg) import removed (#1712, reported by @IndividualGhost1905). The legacy .bbscfg import path on the Slicer page is gone — it silently underdelivered on multi-tier preset matching and conflicted with the Orca Cloud / Bambu Cloud precedence work. Use the cloud sync (Orca Cloud or Bambu Cloud) or local imported presets instead. The SliceModal preset picker now reaches across Imported → Orca Cloud → Bambu Cloud → Standard with proper precedence and cross-tier dedup. - Bambu Lab A2L support added (#1684). New "A2 Series" optgroup in the Add-Printer / Edit-Printer dropdowns and across the SpoolBuddy / inventory surface. The connection diagnostic, AMS slot routing, and camera path all auto-shape themselves to A2L's hardware (Wi-Fi-only, chamber-image protocol on port 6000 instead of RTSPS:322, single-extruder + cutter/plotter head with no deputy-slot routing). Existing X1 / H2 / P1 / P2 / A1 surfaces are unchanged. If you're on an A2L: re-test Configure AMS Slot — the picker now filters profiles to A2L-compatible filaments (#1623 fix below). - Windows installer pipeline overhauled. The installer is self-versioning (filename matches the release tag, plus an unversioned alias on stable / beta), ships its own NSSM binary instead of fetching at build time, stops the Bambuddy service before file copy on upgrade, and bootstraps setuptools + wheel into its embedded Python so the post-install dependency install doesn't fail on a clean machine. Existing Windows installs upgrade in place via the Service / Update entries on the new installer; first-time installs no longer depend on a network trip to a flaky NSSM mirror. Make a backup before upgrading via Settings → Backup → Create Backup. Native install with update.sh snapshots the database automatically and rolls back on failure. Docker and fully-manual paths don't. **Docker** docker compose pull docker compose up -d docker-compose.yml doesn't need refreshing for 0.2.4.7. (If you map the VP passive FTP port range or run the slicer-API sidecar, the 0.2.4.6 upgrade notes still apply — nothing new in 0.2.4.7.) **Native install — recommended path** sudo BRANCH=main /opt/bambuddy/install/update.sh Snapshots the database first and rolls back on failure. **Native install — manual path** sudo systemctl stop bambuddy cd /opt/bambuddy sudo -u bambuddy git fetch --prune --tags --force origin sudo -u bambuddy git checkout main sudo -u bambuddy git reset --hard origin/main sudo /opt/bambuddy/venv/bin/pip install -r requirements.txt sudo systemctl start bambuddy requirements.txt bumps the aiohttp floor to >=3.14.0 this release to clear two upstream advisories. No code change inside Bambuddy — only the floor moves so fresh installs and CI pick up the fix. **Windows install** 0.2.4.7 ships a rebuilt Windows installer with the pipeline improvements from the Upgrade Notes. Download bambuddy-0.2.4.7-windows-x64-setup.exe from this release page (or the unversioned bambuddy-windows-x64-setup.exe alias for an always-latest link). Existing 0.2.4.5 / 0.2.4.6 installs upgrade in place — the installer stops the Bambuddy service, swaps files, restarts the service, and preserves your data directory. --- **Highlights** 0.2.4.7 is a heavy fix-cycle release with one big add — Bambu Lab A2L support (#1684) — and a long tail of contributor-credited fixes across the Virtual Printer, Slicer, Print Queue, and connection-diagnostic surfaces. The Virtual Printer surface got another full sweep driven by #1622 telemetry. The bridge cache now accumulates push_status per-field instead of replacing fields on each push (round 4), overlays incoming dict-shaped fields onto the cache instead of wholesale replacement (round 5, @shaddowlink), and applies the tray_exist_bits empty-slot cleanup to the slicer-facing cache (#1726, @needo37 with full code-level analysis). Net effect: BambuStudio's Device tab no longer greys out between pushalls, and Sync no longer sees phantom-loaded filaments in empty AMS slots. Three env-flagged debug paths landed in the same cycle (wire-payload dump, command-flow trace, bridge-synthesised-reply trace) and stay silent in normal operation. Slicer (SliceModal) is the second-largest theme: full preset-lookup precedence rework + cross-tier dedup + signed-out banner + AMS slot badges (#1712, @IndividualGhost1905). Follow-ups in the same train fix the Orca Cloud / Bambu Cloud preset resolver to pin type and from to CLI-accepted values for the headless slicer-api sidecar, and the Library G-code preview now correctly renders sidecar-sliced .gcode.3mf rows as G-code instead of returning raw ZIP bytes as text/plain (#1709, root cause + fix from @yanglei1980). Print Queue + Archive polish: multi-plate Send All now enqueues one queue item per plate instead of one item per click, archive delete cascades to remove related queue items instead of leaving "cancelled" rows behind, the force-color-match checkbox is no longer missing when scheduling against a specific printer (#1717, @SamNuttall), and the filament-override panel surfaces Bambu Studio's sub-brand colour name instead of the raw 3MF base material (#1718, @SamNuttall). Multi-color filament rows in the Print Log render one swatch per colour instead of a single barely-visible gray dot (#1731 part 1, @IndividualGhost1905). Telegram (and other image-bearing) finish notifications on a reprint-from-archive now ship the new run's finish photo instead of the original print's (#1707, @kycrna). Windows + restore reliability. Beyond the installer pipeline overhaul: /api/local-backup/status no longer 500s on ZoneInfoNotFoundError: 'No time zone found with key UTC' from a missing zoneinfo DB on the Windows installer (a stdlib UTC fallback covers it). Network-interface enumeration on Windows now uses psutil instead of the Linux-only path. Restore pauses timer-based DB writers before the swap, fixing a Postgres deadlock cascade observed during multi-printer restores. --- **New Features** - Bambu Lab A2L support (#1684). New "A2 Series" optgroup in Add-Printer / Edit-Printer dropdowns, with full capability resolution from BambuStudio's machine profile cross-checked against Bambu's official A2L specs page: linear rail, single FDM extruder + integrated cutter/plotter head, Wi-Fi-only (no Ethernet), Low-Rate-Kamera on the chamber-image protocol (port 6000, not RTSPS:322), no heated chamber. The dual-tool-head capability is correctly distinguished from dual-filament extrusion — A2L is not in DUAL_NOZZLE_MODELS, so AMS does not route to a deputy slot (firmware would reject with 07FF_8012). Registry updates touch utils/printer_models.py, firmware_check.py (wiki path follows the established /en/a2l/manual/a2l-firmware-release-history pattern; existing 404 handling makes this safe to ship before Bambu publishes the page), virtual_printer/manager.py (serial prefix 26A19), virtual_printer/mqtt_server.py, PrintersPage.tsx, and SpoolBuddyAmsPage.tsx. Camera and dual-nozzle code paths need no edits — supports_rtsp() correctly falls through to chamber-image and is_dual_nozzle_model() correctly returns False. - Re-print / Schedule modal allows cross-extruder AMS slot picks on dual-nozzle (#1722, reported by @privatsturm). The picker previously gated AMS slot choices to the same extruder as the source plate's filament group. On dual-nozzle hardware that's wrong — operators routinely re-route a left-side filament to a right-side AMS slot when the left bank is empty or busy. Fix removes the gate; the MQTT layer's existing dual-nozzle routing handles the rest. - Support bundle now includes redacted cached push_status per connected printer. The raw push_status payload is the single highest-signal artefact for diagnosing slicer-facing VP issues. The new bundle entry walks the cached payload and scrubs net.info[*].ip plus the documented privacy-sensitive fields before serialising — the live state.raw_data is never mutated. Drops directly into the existing bundle archive alongside the existing log + config dumps. - One-shot device identification probe for unknown printer models. When Bambuddy sees a serial prefix it doesn't recognise on the MQTT bus, it now fires a single push_all-only probe to surface the model code, instead of either silently dropping the connection or polluting the log with repeated unknown-model warnings. Aids future model rollouts (next H2 / A2 / X2 family variant). --- **Changes** - VP MQTT bridge cache shape rework (#1622 rounds 4 + 5). The cache now accumulates push_status per-field instead of replacing fields on each incoming push (round 4, fixes Device-tab greying), and overlays incoming dict-shaped fields onto the cache instead of replacing the whole sub-object (round 5, @shaddowlink, fixes vt_tray going "invalid" right after a slicer filament pick). Field accumulation is bounded by the field allowlist documented in the VP regression matrix. - SliceModal preset-lookup precedence + cross-tier dedup + signed-out banner + AMS slot badges (#1712, reported by @IndividualGhost1905). The 4-tier picker (Imported → Orca Cloud → Bambu Cloud → Standard) now enforces the documented precedence end-to-end with explicit dedup on key collisions, surfaces a signed-out banner per cloud tier instead of silently empty lists, and renders AMS slot badges next to the preset row so operators can see at a glance which slot the preset would land in. The legacy .bbscfg import path was dropped in the same train — see Upgrade Notes. - Print-modal "off" toggles for flow_cali and nozzle_offset_cali now actually suppress the calibration stage. Live-tested on H2D 01.x. The previous behaviour wrote the toggle value into the project_file payload but the firmware still ran the stage; fix routes through the existing dual-nozzle gate and the calibration-suppress field at the MQTT layer. - Support-bundle log noise demoted (#1721 adjacent, observed on the reporter's A1). Benign "not connected" and "may linger" warnings are now INFO-level so the bundle log dumps surface real problems instead of background heartbeat noise. - aiohttp pinned to >=3.14.0 in requirements.txt for two upstream advisories. Bambuddy's aiohttp usage was unaffected by the underlying issues, but the floor moves so fresh installs and CI pick up the fixed runtime. --- **Fixed** **UI / rendering** - Print Log multi-color filament rows now render one swatch per colour instead of a single barely-visible gray dot (#1731 part 1, reported by @IndividualGhost1905). The renderer was averaging the multi-colour RGBA into a single greyscale fallback; the fix splits on the slicer's pipe-separated colour list and renders a small swatch row. - Stats page Failure Analysis widget now renders translated failure reasons instead of raw camelCase keys (#1687 follow-up, reported by @IndividualGhost1905). The GET serialiser was dropping the canonical failure_reason mapping; the fix re-applies the same vocabulary the Archive Edit modal uses. - System page boot time no longer renders with a doubled timezone offset (#1690 follow-up, reported by @IndividualGhost1905). The recorder was emitting a tz-naive datetime that the frontend then localised on top; both boot_time and generated_at now ship as tz-aware UTC. - AMS slot card stays in sync with the new spool's preset name after RFID auto-assigns a new spool. Reporter observed H2D-1 / AMS-B3 / PLA-CF rendering as "Bambu PLA Silk+" until manual refresh. The fix invalidates the AMS slot's cached preset-name lookup on the same event that updates the spool binding. **Virtual printer** - Empty AMS slots no longer forwarded as phantom loaded filaments to BambuStudio Sync (#1726, reported with full code-level analysis by @needo37). The tray_exist_bits empty-slot cleanup now applies to the slicer-facing cache in addition to the live state — Sync sees the same empty-slot picture the real printer reports. - The vt_tray external-spool object no longer goes "invalid" immediately after a slicer filament pick (#1622 round 5, reported by @shaddowlink). The cache was replacing the whole vt_tray sub-object on each push, dropping the slicer's just-picked state; the overlay rework preserves field-level updates. - VP cache no longer drains capability / lifecycle fields between pushalls, which had greyed out Device-tab UIs (#1622 round 4, reported by @shaddowlink). The per-field accumulation fix from the Changes section. **Print queue + dispatch + archive** - Multi-plate Send All now enqueues one queue item per plate instead of one item per click. The route was accepting the plate count from the UI but the queue-insert was firing once per request; fix iterates the plate set on the server side. - Archive delete now removes related queue items instead of leaving "cancelled" rows behind. The cascade was already declared at the schema level but the DELETE route was using a soft-delete path that bypassed it; fix routes the archive delete through the same cascading path the bulk-delete already used. - Finish-photo capture: dispatch no longer force-toggles the printer-side Capture Finish Photo setting (#1721, reported by @agrisci). See Upgrade Notes for the full behaviour change. - Telegram (and other image-bearing) finish notification on a reprint-from-archive no longer ships the original print's finish photo instead of the new run's (#1707, reported by @kycrna). The notification was reading the finish-photo path from the source archive instead of the new archive row. - Print Queue filament-override panel now shows Bambu Studio's sub-brand colour name instead of the raw 3MF base material (#1718, reported by @SamNuttall). The panel was reading directly from the 3MF metadata instead of the resolved Bambu profile. - Force-color-match checkbox no longer missing when scheduling against a specific printer (#1717, reported by @SamNuttall). The Charcoal-style label fix from earlier in the queue cycle was missing on the Specific-Printer panel; this also extends to a related label-fix follow-up (#1718 round 3). **Inventory / AMS / connection diagnostic** - Configure AMS Slot picker now filters filament profiles to the printer model (#1623, reported by @shaddowlink). The list was showing every imported profile regardless of printer compatibility; the fix routes the picker through the same compatibility filter the SliceModal uses. - Connection diagnostic no longer flags external_storage: fail on A1 / A1 Mini (#1703, reported by @MartinNYHC). A1 and A1 Mini have no MicroSD slot; the diagnostic now skips the check for those models with a clear "n/a — printer has no SD slot" surface. - A1 / A1 Mini internal-code map was swapped in PRINTER_MODEL_ID_MAP (surfaced while scoping A2L support, #1684). The swap had no user-visible symptoms but corrupted the printer-model resolver for any code path that round-tripped through the ID map. **Slicer / library** - Library G-code preview returned raw ZIP bytes as text/plain for sidecar-sliced .gcode.3mf rows (#1709, root cause + fix from @yanglei1980). The preview route was branching on filename suffix but the sidecar produces .gcode.3mf — a ZIP wrapper around a .gcode payload. Fix extracts the inner .gcode before serving and pins the Content-Type to text/x-gcode. - Cloud + Orca Cloud preset resolver now pins type and from to CLI-accepted values (#1712 follow-up, reported by maziggy on a Mecha Mewtwo slice). The resolver was passing the user-tier-as-displayed string ("orca_cloud") to the headless slicer-api CLI, which only accepts a fixed enum; fix maps display tiers to CLI tiers explicitly. **Windows / install / restore** - /api/local-backup/status no longer 500s on ZoneInfoNotFoundError: 'No time zone found with key UTC' (from a user's log on the Windows installer). Some Windows hosts ship without the IANA zoneinfo database; the fix falls back to the stdlib UTC implementation when the IANA lookup raises. - Network-interface enumeration on Windows now uses psutil instead of the Linux-only socket path. Affected the Add-Printer custom-subnet picker and any path that listed local interfaces. - In-app updater now routes every git step through app_dir for separate-mount installs (#1715, reported by @francescocozzi). On installs where /opt/bambuddy/data is a separate mount from /opt/bambuddy, the updater's git commands ran from the data dir and failed silently on the .git lookup; fix explicitly passes -C app_dir. - Restore now pauses timer-based DB writers before swap, fixing a Postgres deadlock cascade. Multi-printer restores were triggering concurrent timer writers against the same connection pool as the restore transaction; fix gates the timer loop on a "restore in progress" flag.
Bambuddy
Your printers. No cloud. Your rules.
Self-hosted command center for Bambu Lab — from one A1 to a 40-printer farm.
🎮 Try the Live Demo • Features • Screenshots • Quick Start • Documentation • Discord • Contributing
Spin up your own private Bambuddy in ~10 seconds — no install, no signup, 30-minute session.
📰 As Featured In
"Bambuddy is the companion app that Bambu Lab should have built from day one." — Adam Conway, XDA-Developers
Two leading 3D-printing publications independently concluded that Bambuddy's feature set already exceeds Bambu's own cloud:
"The features seem to exceed those provided by Bambu Lab's own cloud." — Fabbaloo
"The list of functions seems so extensive that it even goes beyond what Bambu Lab offers in its own cloud." — 3Druck.com
🌐 NEW: Remote Printing with Proxy Mode
Print from anywhere in the world — Bambuddy's new Proxy Mode acts as a secure relay between your slicer and printer:
- 🔒 End-to-end TLS encryption — FTP, file transfer, and camera are transparently proxied with the printer's real TLS certificate
- 🛡️ Optional Tailscale integration — per-VP toggle + Docker socket mount surface the host's Tailscale IP on the VP card, so you know which
100.x.x.xto paste into the slicer when you want a virtual printer reachable over your tailnet (setup). Bambuddy's self-signed CA import is still required on the slicer side: Bambu Studio / OrcaSlicer validate printer TLS against a bundled BBL CA (not the system trust store), and their Add Printer dialog is IP-only (no hostname to match an LE cert against), so a publicly-trusted cert can't help on either dimension. Tailscale's role is the private tunnel (reachability from anywhere, no port forwarding), not cert-import elimination. - 🌍 No cloud dependency — Direct connection through your own Bambuddy server
- 🔑 Uses printer's access code — No additional credentials needed
- ⚡ Full-speed printing — Transparent TCP proxy, only MQTT is decrypted for IP rewriting
Perfect for remote print farms, traveling makers, or accessing your home printer from work.
🍰 NEW: Integrated Slicing — Slice & Print, All In One Place
No desktop slicer required. Drop an STL or 3MF into Bambuddy's File Manager, hit Slice, and the result lands as a ready-to-print .gcode.3mf in the same folder — without ever opening Bambu Studio or Orca Slicer.
- 🍰 One-click slicing — Slice from any browser. The job runs server-side in a tiny sidecar container, progress streams back as a toast, and the sliced file appears in your library when it's done.
- 📱 Slice from your phone or tablet — Bambuddy's PWA + the new server-side slicer means you can drop an STL in from mobile and queue a print without ever touching a desktop.
- 🎒 Bring your own profiles — Import a
Printer Preset Bundle(.bbscfg) exported from Bambu Studio: pick a curated printer + process + filament triplet from a dropdown in the Slice dialog, no more juggling JSON files. - 🔄 Re-slice for a different printer in one click — Open any sliced archive in Bambuddy and re-slice it for any printer, including across the single-nozzle ↔ dual-nozzle (H2D / H2D Pro) boundary that BambuStudio's CLI would normally reject. Bambuddy detects the class change and auto-arranges objects laid out for the source bed (e.g. X1C 256×256) so they land safely on the target (e.g. H2D 350×320 with its per-nozzle dead zones).
- 🍱 Slice all plates at once — Multi-plate projects (parted statues, multi-part kits) get a "Slice all N plates" toggle in the Slice dialog. One click produces a single
.gcode.3mfcontaining every plate's gcode, ready for the printer. The toast shows "Plate 2 of 5 — Generating G-code (47%)" as the loop runs. - 🔁 Same dispatch as the rest of Bambuddy — The sliced output flows into the existing queue / plate-picker / AMS-mapping path, so all the regular conveniences (multi-printer dispatch, AMS routing, scheduled prints) just work.
Optional but recommended — drop the slicer-api/ Compose stack next to your Bambuddy install and the Slice button lights up everywhere.
Why Bambuddy?
- Own your data — All print history stored locally, no cloud dependency
- Works offline — Uses Developer Mode for direct printer control via local network
- Full automation — Schedule prints, auto power-off, get notified when done
- Multi-printer support — Manage your entire print farm from one interface
✨ Features
📦 Print Archive
📊 Monitoring & Control
⏰ Scheduling & Automation
📁 File Manager (Library)
🌍 MakerWorld Integration
📁 Projects
|
🔔 Notifications
🧵 Spool Inventory
🔧 Integrations
🖨️ Virtual Printer & Remote Printing
🛠️ Maintenance & Support
🔒 Optional Authentication
|
Plus: Configurable slicer (Bambu Studio / OrcaSlicer) • Customizable themes (style, background, accent) • Mobile responsive • Keyboard shortcuts • Multi-language (EN/DE/JA/IT) • Auto updates • Database backup/restore • System info dashboard
🎬 Demo
Spin up your own private Bambuddy with simulated printers and pre-loaded print history. Click around freely — it's your sandbox. ~10 seconds to spawn, 30-minute session, no signup.
Prefer a video walkthrough?
Click to watch the demo on YouTube
📸 Screenshots
Click to expand screenshots
Real-time printer monitoring with AMS status
Print archive with 3D preview and project assignment
Re-print with AMS filament mapping preview
Built-in timelapse editor with trim, speed, and music
Group related prints into projects
Project detail view with assigned archives
Project timeline and print history
Print scheduling and queue management
Schedule prints for specific date and time
Customizable statistics dashboard
Maintenance tracking per printer
Configure maintenance types and intervals
Bambu Cloud filament profiles
Edit filament preset settings
Pressure advance (K-factor) profiles
Edit K-factor profile settings
General configuration and integrations
Smart plug control and energy monitoring
Multi-provider notification system
API keys and webhook endpoints
Virtual printer configuration
Virtual printer appears in Bambu Studio/Orca Slicer
MQTT debug logging for troubleshooting
Quick power plug control in sidebar
🚀 Quick Start
Requirements
- Python 3.10+ (3.11/3.12 recommended)
- Bambu Lab printer with Developer Mode enabled (see below)
- "Store sent files on external storage" enabled in Bambu Studio/OrcaSlicer
- Same local network as printer
Installation
Windows (Native Installer)
Self-contained .exe — no Python, Node, Docker, or Git required on the target machine. The installer bundles Python 3.13, the React frontend, ffmpeg, and registers Bambuddy as a Windows service.
Download the latest installer:
https://github.com/maziggy/bambuddy/releases/latest/download/bambuddy-windows-x64-setup.exe
Run it (one-time UAC prompt — admin install) → Bambuddy starts as a Windows service and the dashboard opens at http://localhost:8000 automatically. Data lives at C:\ProgramData\Bambuddy\, install at C:\Program Files\Bambuddy\. To update, just run a newer installer over the existing install — your database and archives are preserved.
SmartScreen warning: until our SignPath OSS code-signing approval lands, you'll see "Windows protected your PC" on first run. Click More info → Run anyway.
See the Windows Installer Guide for service management, logs, and troubleshooting.
Docker (Linux / macOS / Windows via Docker Desktop)
Option A: Pre-built image (fastest)
mkdir bambuddy && cd bambuddy
curl -O https://raw.githubusercontent.com/maziggy/bambuddy/main/docker-compose.yml
docker compose up -d
Option B: Build from source
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy
docker compose up -d --build
Open http://localhost:8000 in your browser.
Multi-architecture support: Pre-built images are available for
linux/amd64andlinux/arm64(Raspberry Pi 4/5).
macOS/Windows users: Docker Desktop doesn't support
network_mode: host. Edit docker-compose.yml: comment outnetwork_mode: hostand uncomment theports:section. Printer discovery won't work - add printers manually by IP.
Linux users: If you get "permission denied" errors, either prefix commands with
sudo(e.g.,sudo docker compose up -d) or add your user to the docker group.
Docker Configuration & Commands
Environment Variables:
| Variable | Default | Description |
|---|---|---|
TZ |
UTC |
Your timezone (e.g., America/New_York, Europe/Berlin) |
PORT |
8000 |
Port BamBuddy runs on (with host networking mode) |
DEBUG |
false |
Enable debug logging |
LOG_LEVEL |
INFO |
Log level: DEBUG, INFO, WARNING, ERROR |
Data Persistence:
| Volume | Purpose |
|---|---|
bambuddy.db |
SQLite database with all your print data (not used with PostgreSQL) |
archive/ |
Archived 3MF files and thumbnails |
logs/ |
Application logs |
Updating:
# Pre-built image: just pull the latest
docker compose pull && docker compose up -d
# From source: rebuild after pulling changes
cd bambuddy && git pull && docker compose up -d --build
Daily Beta Builds:
Beta builds with the latest fixes are pushed regularly to the same beta version tag:
# Pull the current beta
docker pull ghcr.io/maziggy/bambuddy:0.2.2b1
# or from Docker Hub
docker pull maziggy/bambuddy:0.2.2b1
Use Watchtower to automatically update when new daily builds are pushed.
Note: Beta builds use version tags like
0.2.2b1— they are never tagged aslatest. Your stable installation won't auto-update to a beta unless you explicitly pull a beta tag.
Useful Commands:
# View logs
docker compose logs -f
# Stop/Start
docker compose down
docker compose up -d
# Shell access
docker compose exec bambuddy /bin/bash
Custom Port:
ports:
- "3000:8000" # Access on port 3000
Reverse Proxy (Nginx):
server {
listen 443 ssl http2;
server_name bambuddy.yourdomain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 86400;
}
}
Note: WebSocket support is required for real-time printer updates.
Network Mode Host (required for printer discovery and camera streaming):
services:
bambuddy:
build: .
network_mode: host
Note: Docker's default bridge networking cannot receive SSDP multicast packets for automatic printer discovery. When using
network_mode: host, Bambuddy auto-detects your network subnet and can discover printers via subnet scanning in the Add Printer dialog.
Manual Installation (Linux/macOS)
# Clone and setup
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Run
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000
Open http://localhost:8000 and add your printer!
Need detailed instructions? See the Installation Guide
Windows Native Installation
Windows PowerShell (run as Administrator — the installer self-elevates via UAC if not):
powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/maziggy/bambuddy/main/install/windows-installer.ps1 -OutFile windows-installer.ps1; .\windows-installer.ps1"
Installs Bambuddy natively on Windows using Git, Python, a virtual environment, separate data/log directories, and optional NSSM Windows Service registration. See the Windows Installer Guide for parameters and unattended-install options.
Enabling Developer Mode
Developer Mode allows third-party software like Bambuddy to control your printer over the local network.
- On printer: Settings → Network → LAN Only Mode → Enable
- Enable Developer Mode (appears after LAN Only Mode is enabled)
- Note the Access Code displayed
- Find IP address in network settings
- Find Serial Number in device info
Note: Developer Mode disables cloud features but provides full local control. Standard LAN Mode (without Developer Mode) only allows read-only monitoring.
Slicer Settings
In Bambu Studio or OrcaSlicer, enable "Store sent files on external storage" so that print files (3MF) are saved to the printer's SD card. Bambuddy needs these files to extract thumbnails and 3D model previews.
- Open Bambu Studio or OrcaSlicer
- Go to the Device tab for your printer
- In Print Options, enable Store Sent Files on External Storage
📚 Documentation
Full documentation available at wiki.bambuddy.cool:
- Installation — All installation methods
- Getting Started — First printer setup
- Features — Detailed feature guides
- Troubleshooting — Common issues & solutions
- API Reference — REST API documentation
🖨️ Supported Printers
| Series | Models |
|---|---|
| X1 | X1, X1 Carbon, X1E |
| X2 | X2D |
| H2 | H2D, H2D Pro, H2C, H2S |
| P1 | P1P, P1S |
| P2 | P2S |
| A1 | A1, A1 Mini |
| A2 | A2L |
🛠️ Tech Stack
| Component | Technology |
|---|---|
| Backend | Python, FastAPI, SQLAlchemy |
| Frontend | React, TypeScript, Tailwind CSS |
| Database | SQLite (default) or PostgreSQL |
| 3D Viewer | Three.js |
| Communication | MQTT (TLS), FTPS |
🤝 Contributing
Contributions welcome! Ways to help:
- 📝 Document — Improve the wiki and guides (urgently needed!)
- Test — Report issues with your printer model
- Translate — Add new languages
- Code — Submit PRs for bugs or features
- 🔒 Security review — (specifically wanted, see below)
Not sure where to start? Reach out on Discord or email martin@bambuddy.cool — I'll help you find something that fits.
🔒 Looking for a security-focused contributor
I'm bringing on a contributor whose specific focus is keeping an eye on Bambuddy's security.
Concretely:
Track the dev branch and flag changes touching auth, permissions, token handling, or the CI security backstops. Async post-merge — no gating of in-flight PRs.
What matters more than formal qualifications: fail-closed thinking by default, comfortable reading the auth layer (FastAPI + SQLAlchemy on the backend, a small React surface), willing to push back on except Exception shapes in security-sensitive code.
No fixed time commitment. If you're interested — or know someone who fits — email martin@bambuddy.cool or DM on Discord.
See CONTRIBUTING.md for guidelines.
📄 License
AGPL-3.0 License — see LICENSE for details.
🙏 Acknowledgments
- SpoolEase by yanshay — early inspiration for NFC-based spool tracking and AMS inventory concepts
- Bambu Lab for amazing printers
- The reverse engineering community for protocol documentation
- All testers and contributors
💖 Support Bambuddy
Bambuddy stays independent because real people support it directly. If Bambuddy makes your printers more useful, please consider:
- GitHub Sponsors — five recurring tiers from $5/mo (Backer) to $300/mo (Corporate). Supporter+ ($15/mo) get access to a private sponsors space with a monthly newsletter and early release notes. Patron+ ($35/mo) vote on the quarterly roadmap. Sustaining Sponsor+ ($150/mo) get a direct async email line for technical questions (~2-3 business days). Corporate ($300/mo) get priority email response (next business day), README header logo, sitewide footer logo on bambuddy.cool, and Press page placement.
- Ko-fi — one-time tip or recurring.
Sponsors get listed in BACKERS.md. Need commercial support (SLA, multi-printer consulting)? Email martin@bambuddy.cool.
Made with ❤️ for the 3D printing community
Join our Discord •
Report Bug •
Request Feature •
Documentation