bambuddy/slicer-api/README.md

Slicer-API sidecar (optional)

Self-contained Docker Compose stack that runs HTTP wrappers around the OrcaSlicer and/or Bambu Studio CLI. Bambuddy's Slice action calls these to slice models server-side, no desktop slicer required.

This folder is optional. Bambuddy works without it — Slice falls back to opening the model in the user's local desktop slicer via URI scheme. Enable the API path by:

1. Starting one or both services here
2. Settings → Slicer → Use Slicer API = on
3. Set Slicer sidecar URL for whichever slicer you've started

Quick start

cd slicer-api/
cp .env.example .env       # edit ports if you like

# OrcaSlicer only (default profile):
docker compose up -d
curl http://localhost:3003/health

# Both slicers:
docker compose --profile bambu up -d
curl http://localhost:3001/health   # bambu-studio-api
curl http://localhost:3003/health   # orca-slicer-api

First start pulls pre-built images from GHCR (~110 MB OrcaSlicer, ~220 MB BambuStudio). No local build, no git in the BuildKit worker, works on QNAP / Synology / Container Station out of the box.

Both images are linux/amd64 only. OrcaSlicer's ARM64 build is on hold pending an upstream extraction fix; BambuStudio doesn't publish ARM64 at all. For ARM64 hosts (Raspberry Pi 4/5, Apple Silicon Linux), run the sidecar on a separate x86_64 box and point Bambuddy at it via the Sidecar URL field — the sidecar doesn't need to live next to Bambuddy.

If a separate x86_64 box isn't an option, the amd64 images can be run on an ARM64 host under emulation — experimental, roughly 3-6x slower than native, and a stopgap until native ARM64 images ship. See Experimental setup for ARM64 below.

Ports

Service	Default host port	Why this port
orca-slicer-api	3003	Bambuddy's virtual-printer feature reserves 3000 and 3002
bambu-studio-api	3001	First free port in that range

Override via ORCA_API_PORT / BAMBU_API_PORT in .env.

Bambuddy wiring

In the Bambuddy UI: Settings → Slicer:

• Preferred Slicer: pick OrcaSlicer or Bambu Studio.
• Use Slicer API: turn on.
• Sidecar URL: paste the full URL of the chosen slicer's sidecar. Default values match the Compose defaults:
  • OrcaSlicer: http://localhost:3003
  • Bambu Studio: http://localhost:3001

Leaving the URL field blank uses the SLICER_API_URL / BAMBU_STUDIO_API_URL environment defaults from Bambuddy's config.

Where the images live

Pre-built images are published to two registries on every Bambuddy stable release:

• ghcr.io/maziggy/orca-slicer-api:latest / docker.io/maziggy/orca-slicer-api:latest
• ghcr.io/maziggy/bambu-studio-api:latest / docker.io/maziggy/bambu-studio-api:latest

Each release also publishes a versioned tag (:bambuddy-X.Y.Z) so you can pin to the sidecar that shipped alongside a specific Bambuddy release — set SIDECAR_TAG=bambuddy-0.2.5 in .env.

Both images are built from the maziggy/orca-slicer-api fork (bambuddy/profile-resolver branch). The fork patches AFKFelix's upstream wrapper with the inherits: chain resolver, from: "User" → "system" rewrite, # clone-prefix strip, and sentinel-value strip — all empirically required to slice real GUI exports without segfaulting the CLI. Once those land upstream, the compose file can be flipped back to ghcr.io/afkfelix/orca-slicer-api.

Updating

OrcaSlicer only (the default):

docker compose pull
docker compose up -d

With the Bambu Studio sidecar — the profile flag belongs on both commands:

docker compose --profile bambu pull
docker compose --profile bambu up -d

bambu-studio-api sits behind profiles: [bambu], and a bare docker compose pull skips profile-gated services silently: it reports success, restart: unless-stopped keeps the old container serving, and you stay on the old image no matter how often you repeat it. To update one sidecar only, name it — docker compose pull bambu-studio-api && docker compose up -d bambu-studio-api — which enables its profile implicitly.

Compose pulls the current :latest (or whatever SIDECAR_TAG you've pinned to) and recreates the containers.

To roll back to the sidecar that shipped with a previous Bambuddy release, set SIDECAR_TAG=bambuddy-X.Y.Z in .env and re-run the two commands above.

Experimental setup for ARM64

Runs the linux/amd64 images on an ARM64 host under QEMU emulation, via the docker-compose.arm64.yml override in this folder. Expect roughly 3-6x slower slicing than native, worsening with model complexity. This is a stopgap until native ARM64 images ship, not a replacement for running the sidecar on an x86_64 box — if you have one, use it.

Set up QEMU binfmt on the host first, or the containers fail with exec format error. On Debian/Ubuntu that is qemu-user-static plus binfmt-support; Docker Desktop on Apple Silicon already has it. The per-distribution commands are in the wiki — do that before the steps below.

Quick start for ARM64

cd slicer-api/
cp .env.example .env       # edit ports if you like

# Make every later `docker compose` command pick up the ARM64 override:
echo 'COMPOSE_FILE=docker-compose.yml:docker-compose.arm64.yml' >> .env

# OrcaSlicer only (default profile):
docker compose up -d
curl http://localhost:3003/health

# Both slicers:
docker compose --profile bambu up -d
curl http://localhost:3001/health   # bambu-studio-api
curl http://localhost:3003/health   # orca-slicer-api

That COMPOSE_FILE line is what makes the rest of this README work unchanged on ARM64 — Updating included. Without it every command has to name both files (docker compose -f docker-compose.yml -f docker-compose.arm64.yml …), and the first bare docker compose pull or up -d drops the override: on a host with no amd64 emulation registered for that image you get a manifest error, and once native ARM64 images exist you would silently switch between them and back.

Troubleshooting

• address already in use on port 3000 or 3002 — Bambuddy's virtual-printer feature owns those. Don't change ORCA_API_PORT to 3000 or 3002.

• /health reports version: "unknown" — cosmetic. The bundled binary works; the wrapper just couldn't parse the version string from the slicer's --help output (BambuStudio's format differs from OrcaSlicer's, which is what the wrapper was tuned for).

• Slice returns "Failed to slice the model" — the wrapper hides the CLI's stderr. Re-run inside the container to see it:

  docker exec orca-slicer-api /app/squashfs-root/AppRun --slice 1 \
      --load-settings "/path/to/printer.json;/path/to/preset.json" \
      --load-filaments /path/to/filament.json \
      --allow-newer-file --outputdir /tmp/out /path/to/model.3mf