Wiki · Latest release · Public demo · Docker Hub

Demo login: admin / printbuddy

Quick start · Providers · Features · Home Assistant · Development · Printbuddy Mascot

[!WARNING] Printbuddy is under active development.

Use it for homelab testing, development, and controlled deployments. Features and provider-specific workflows are moving quickly and may change between releases.

What is Printbuddy?

Printbuddy is a self-hosted 3D printer management and monitoring platform.

It gives you one central dashboard to monitor and manage your 3D printers across different ecosystems. Printbuddy fully supports Bambu Lab printers, including their printer state, active print progress, job information, AMS/filament data, and other Bambu-specific details where available.

Besides Bambu Lab printers, Printbuddy is also designed to support other printer platforms such as:

• Klipper/Moonraker printers
• PrusaLink / PrusaConnect printers
• Elegoo and Creality Klipper-based printers
• additional printer types in the future

The goal is to make Printbuddy a proper multi-printer operations dashboard for homelabs, print farms, and maker spaces.

What is the difference?

The main difference is scope.

Bambuddy is Bambu-only. Printbuddy fully supports Bambu Lab printers too, but it does not stop there.

Printbuddy takes the Bambu functionality and expands the idea into a vendor-neutral 3D printer management platform. That means you can manage Bambu printers alongside Klipper/Moonraker, PrusaLink, and other supported printer types from one interface.

Quick start

Docker Compose on Linux

The default docker-compose.yml is optimized for Linux hosts and uses host networking so printer discovery, cameras, MQTT/FTP, and virtual-printer ports can work without container NAT surprises.

mkdir printbuddy && cd printbuddy
curl -fsSLO https://raw.githubusercontent.com/vmhomelab/Printbuddy/main/docker-compose.yml
docker compose up -d

Open Printbuddy:

http://<docker-host-ip>:8000

Useful checks:

docker compose ps
docker compose logs -f printbuddy
curl http://127.0.0.1:8000/health

Docker Desktop / bridge networking

Docker Desktop on Windows and macOS does not support Linux-style network_mode: host.

For Docker Desktop:

1. Comment out network_mode: host in docker-compose.yml.
2. Uncomment the ports: block.
3. Add printers manually by IP address; automatic discovery may not cross Docker Desktop networking.
4. Set VIRTUAL_PRINTER_PASV_ADDRESS=<docker-host-ip> if you use virtual-printer FTP passive mode.

Images

Stable releases are published to Docker Hub:

docker pull docker.io/vmhomelabde/printbuddy:latest

Development builds are published from dev:

docker pull docker.io/vmhomelabde/printbuddy:dev

Use latest unless you intentionally want to test current development work.

Supported provider families

Bambu remains the default provider for older printer records so existing installations keep working during migration.

Features

• Multi-printer dashboard with provider-aware status normalization.
• Real-time monitoring for supported printer families (including add-ons like the Panda Breath form Biqu).
• Printer file manager with provider-specific upload, list, download, delete, and print actions.
• Print archives, logs, metadata capture, usage tracking, and reprint workflows.
• Local filament inventory with Spoolman integration and non-AMS loaded-spool assignment support.
• Open Filament Database-assisted spool creation.
• Notification providers including Telegram, Discord, email, Pushover, ntfy, and other configured channels.
• Optional authentication, API keys, role/group-style permissions, and MFA support.
• Bambu virtual-printer/proxy modes for supported slicer workflows.
• Optional slicer sidecars for OrcaSlicer and Bambu Studio API workflows.
• Smart-home and automation hooks, including MQTT/Home Assistant-oriented integrations.
• Optional Docker self-update sidecar for controlled Compose-based updates.
• SQLite by default, with optional PostgreSQL through DATABASE_URL.

Screenshots

Additional current screenshots and walkthroughs live in the wiki and release notes.

Configuration

Common environment variables from the provided Compose file:

Runtime data is stored in Docker volumes by default:

See DEPLOYMENT.md, UPDATING.md, and docs/self-update-sidecar.md for operational details.

Home Assistant

Printbuddy can be used with Home Assistant in two ways:

• Home Assistant add-on: runs Printbuddy directly inside Home Assistant with Ingress, persistent add-on storage, and LAN printer access through host networking. Repository: vmhomelab/printbuddy-ha-addon
• Home Assistant custom integration: connects Home Assistant to an existing Printbuddy instance and exposes configured printers as Home Assistant devices and telemetry entities. Repository: vmhomelab/ha-printbuddy-integration

Wiki pages:

• Printbuddy Home Assistant Add-on
• Printbuddy Home Assistant Integration

Updating

Updating via the UI

To use the update feature over the UI, please make sure that you edited the docker-compose.yml file accordingly. See here on what to do.

For Docker Compose deployments:

docker compose pull
docker compose up -d

If your Compose file is old, refresh it from main and compare it with your local changes before replacing it:

curl -fsSL https://raw.githubusercontent.com/vmhomelab/Printbuddy/main/docker-compose.yml \
  -o docker-compose.yml.new

For native installs, use the included updater when available:

sudo /opt/printbuddy/install/update.sh

Take a backup before major upgrades. Settings → Backup can export state from inside the app; Docker users can also back up the printbuddy_data volume manually.

Repository workflow

Development happens on dev first, then tested changes are merged to main for stable releases.

dev  -> active development and test images
main -> stable releases and latest image metadata

Release flow:

1. Prepare and test changes on dev.
2. Bump APP_VERSION for the release.
3. Merge approved changes into main.
4. Create the matching GitHub release/tag.
5. Publish and verify Docker images for the exact released commit.

Development

Backend

python3 -m venv venv
./venv/bin/pip install -r requirements.txt -r requirements-dev.txt

ruff check backend/
ruff format --check backend/

cd backend
../venv/bin/python -m pytest tests/ --tb=short

Frontend

cd frontend
npm ci
npm run lint
npx tsc --noEmit
npm run test:run
npm run build

Before committing docs or code changes, run:

git diff --check
git status --short --branch

Printbuddy

Printbuddy has its own printable mascot.

• MakerWorld: https://makerworld.com/de/models/2894134-your-printbuddy#profileId-3234154
• Printables: https://www.printables.com/model/1746692-your-printbuddy

Project links

• Wiki: https://wiki.printbuddy.tech
• Demo: https://demo.printbuddy.tech
• GitHub releases: https://github.com/vmhomelab/Printbuddy/releases
• Docker image: https://hub.docker.com/r/vmhomelabde/printbuddy
• Home Assistant add-on: https://github.com/vmhomelab/printbuddy-ha-addon
• Home Assistant integration: https://github.com/vmhomelab/ha-printbuddy-integration
• Project board: https://github.com/users/vmhomelab/projects/4/views/1

Attribution and license

Printbuddy is a modified fork of an upstream AGPL-3.0 project. The repository keeps the upstream license and history context, and Printbuddy-specific modification notices are documented in NOTICE-modifications.md.

See LICENSE for the full AGPL-3.0 license text.

Star history

Printbuddy
Your tiny helper for keeping the printer chaos under control.