File Manager¶

Browse, download, and manage files in your local Bambuddy library.

Overview¶

The File Manager lets you:

• Browse files in your local library
• Mount external folders from NAS, USB, or network shares
• Upload files including ZIP archives
• Download files to your computer
• Rename files and folders
• Delete unwanted files
• View file details and metadata
• Print sliced files with ASAP, Queue, or Schedule
• Link folders to projects or archives

External Folders¶

External folders let you surface a host directory (a NAS mount, a USB drive, a local prints folder) inside Bambuddy's library without copying any files. They appear alongside the managed library and can be browsed, slice-previewed, and printed from like any other folder.

Operator configuration¶

As of v0.2.5b1 (GHSA-r2qv follow-up) the feature is opt-in for operators. The BAMBUDDY_EXTERNAL_ROOTS environment variable controls which host paths users are permitted to register as external folders:

In Docker, also bind-mount the host path into the container at the same path you list in BAMBUDDY_EXTERNAL_ROOTS — see the Docker → External library folders tip for a complete example. Read-only (:ro) bind mounts are recommended unless you want users uploading files back into the host share.

Registering an external folder¶

With the env var set, any user with Settings → Update permission can:

1. Open File Manager → Add external folder (top right).
2. Enter a name and the absolute path inside the container (must be within BAMBUDDY_EXTERNAL_ROOTS).
3. Choose Read-only to prevent uploads to this folder (recommended for shared NAS mounts), or leave unchecked for read/write.
4. Click Add. Bambuddy scans the folder and surfaces 3MFs, STLs, gcode, and image files.

The folder appears in the sidebar with the icon and persists across restarts. Deleting an external folder from the UI only removes Bambuddy's index entry — the host files are not touched.

External folders security stance¶

The pre-v0.2.5b1 implementation used a denylist of system directories (/proc, /sys, /dev, ...). Everything else passed, including /data (Bambuddy's own data directory containing other users' archives), /root, arbitrary NFS/SMB mounts the operator did not realise the container could see, and the Bambuddy log directory. That was the same fail-open-on-growth shape as the GHSA-r2qv-8222-hqg3 finding on the permission system: an attacker did not need a CVE, the codebase grew into the exposure on its own as new file extensions became scannable.

The v0.2.5b1 fix replaces the denylist with the BAMBUDDY_EXTERNAL_ROOTS allowlist. Bambuddy's own data / log / static / archive directories are hardcode-rejected even if the operator over-broadens the allowlist (e.g. accidentally sets / for testing), so configuration mistakes cannot expose internal state. The route is additionally gated on SETTINGS_UPDATE (was LIBRARY_UPLOAD) since registering a host filesystem path is an operator-class capability that crosses user boundaries.

If an existing deployment used the feature before v0.2.5b1, the external folders remain in the database after upgrade but stop working until the operator sets BAMBUDDY_EXTERNAL_ROOTS to cover the paths in use. The UI surfaces a clear error pointing at the variable.

Accessing File Manager¶

1. Click File Manager in the sidebar
2. Or navigate to /file-manager in the URL

File Browser¶

Library Structure¶

Your library contains uploaded and archived files:

• Folders for organizing files
• 3MF and sliced gcode files
• Linked folders connected to projects/archives

File Information¶

Each file shows:

• Filename
• Size
• File type icon
• Print count (if printed before)
• Uploaded by (when authentication is enabled)
• Last-modified date (optional — toggle it on from the sort controls; see Sorting)

Navigation¶

Browsing¶

• Click folders to enter
• Click ← to go back
• Click root to return home

Top-level sidebar entries¶

The two entries at the top of the folder sidebar represent scopes, not folders:

Click any individual folder in the tree below — internal or external — to scope to that folder's contents directly; the per-folder view is unchanged.

Folder sidebar preferences¶

A small set of controls in the folder sidebar header lets you tailor how the tree is rendered. All preferences are stored in your browser and applied on every subsequent page load.

Sorting¶

Sort files by:

• Name (A-Z, Z-A)
• Size (largest/smallest)
• Date (newest/oldest) — uses each file's real modification date, so external files order exactly as ls -t does
• Type
• Print count

Filtering¶

Filter by file type:

• All files
• 3MF only
• Videos only

Search inside subfolders (#1268)¶

When a folder is selected and you type into the search box, Bambuddy automatically widens the search to include every file in the selected folder and all of its descendants — so a file two or three levels deep is still findable from the parent. A small Including subfolders caption appears under the search input whenever this widened scope is active.

The widening only happens while the search box is non-empty; clearing the search returns the listing to its narrow single-folder scope so you can browse the immediate contents again without scroll fatigue. Selecting the All Files / All Internal / All External sidebar entries already returns a union view, so the recursive flag is implicit there too.

The query runs as a single recursive CTE on the server, not as a per-folder fan-out — performance scales to libraries with thousands of nested folders without N+1 round-trips.

Folder description panel (#1268)¶

If a folder contains a markdown file named README.md, readme.md, or description.md (case-insensitive), Bambuddy renders it in a collapsible panel above the file list when you select that folder. Any other *.md file in the folder will also work — README / description are simply preferred when multiple are present.

• Format: GitHub-flavored Markdown — headings, lists, tables, task lists, strikethrough, footnotes, code blocks, blockquotes, and links all render. Write links explicitly as [text](https://example.com) or <https://example.com>; a bare https://example.com typed into the text stays plain text and is not turned into a link (see #2971).
• Source: any markdown file uploaded to the folder via the normal File Manager upload, or scanned in from an external folder.
• Size limit: 512 KiB of source bytes; longer files render the leading portion and surface a Truncated chip in the panel header.
• Safety: raw HTML embedded inside the markdown is ignored — the renderer only emits the parsed markdown tags. Links open in a new tab.

Use it to keep print settings, material recommendations, or post-processing notes alongside the model files themselves. Drop a README.md in a folder and it's there next to the prints — no separate doc system, no Spoolman cross-reference required.

Tags (#1268)¶

Folders express hierarchy (every file lives in exactly one); tags are the orthogonal labels that cut across folders. A single file can carry as many tags as you want — toy, kid-safe, petg-only, failed-twice, gift, whatever you use to think about your library.

Why both?

• A folder structure forces a single home for each file ("Toys/Cars/Race/robot.3mf").
• Tags let you ask "show me every toy regardless of where it lives" without restructuring anything.
• Both work together — the tag filter intentionally ignores the selected folder so a tag query returns every matching file in the whole library.

Manage the tag catalog

Click Tags in the File Manager toolbar to open the catalog. From there you can:

• Create a tag — case-insensitive uniqueness (Toys / toys / TOYS collapse to the same row).
• Rename a tag — collisions return a clear error rather than silently merging.
• Delete a tag — the chip disappears from every file that carried it. The files themselves and their other tags are untouched. The confirm dialog warns you when a tag is in use so you don't delete a popular one by mistake.
• Click a row to push that tag into the filter and close the modal.

Tag a file

Tags appear as small green chips:

• Grid view: chips render below the file's metadata in the card.
• List view: chips live in a dedicated Tags column between Prints and Actions.
• Clicking a chip adds that tag to the active filter (or removes it if it was already active).

Tag multiple files at once

Select files with the checkbox, then click Tag in the multi-select toolbar:

• Choose Add to selected files or Remove from selected files.
• Tick the tags you want to apply.
• The "create new tag" field at the bottom of the modal lets you add a tag and apply it in the same flow.

Filter by tag

A filter rail above the file list shows every catalog tag as a chip. Click an inactive chip to add it to the filter; click an active one (with the ×) to remove it. Multiple active tags combine with AND semantics — only files carrying every selected tag appear. Clear all resets the filter.

Because tags are cross-cutting, the folder you have selected is ignored while a tag filter is active — that's by design, so "every toy" really means every toy, not "every toy in this folder."

Downloading Files¶

Single File¶

1. Find the file
2. Click Download
3. File saves to your computer

Multiple Files¶

1. Select files (checkbox)
2. Click Download Selected
3. Files download (may be zipped)

Drag-and-Drop Upload¶

Drop files anywhere on the File Manager page to start uploading — no need to open the upload modal first. The file picker still lives behind the Upload Files toolbar button if you prefer that flow, but the page-wide drop zone shortcuts the same modal: a full-screen overlay appears once you drag a file over the page, and on release the upload modal opens pre-populated with the dropped files.

• Accepts any file type the upload modal accepts (3MF, STL, ZIP, images).
• Hidden when you lack library:upload permission.
• The overlay self-clears on cancel — drag back outside the browser window, press Escape mid-drag, or release outside the page all return you to the normal view without a refresh.

ZIP File Uploads¶

Upload ZIP archives to automatically extract their contents into your library.

Uploading a ZIP File¶

1. Click the Upload Files button in the toolbar OR drag a .zip file onto the page
2. Select a .zip file from your computer (skipped if you dragged-and-dropped)
3. The upload modal will detect it's a ZIP file
4. Choose whether to preserve folder structure from the ZIP
5. Click Extract to upload and extract

Extraction Options¶

What Gets Extracted¶

• 3MF files with thumbnail and metadata extraction
• Gcode files with print time and filament detection
• Other supported file types

Progress Indicator¶

During extraction:

• Progress shows number of files extracted
• Thumbnails and metadata are generated for each file
• Errors are reported if any files fail to extract

STL and PDF Thumbnail Generation¶

Bambuddy renders grid thumbnails for STL models and PDF documents itself, so both are easy to identify in your library without opening them.

Automatic Generation on Upload¶

When uploading STL files:

1. Click the Upload button
2. Select your STL file(s)
3. Check Generate thumbnails for STL files option
4. Click Upload

Thumbnails are generated automatically during the upload process.

PDF files get their first page as the thumbnail on every upload; the checkbox only governs STL, because a mesh render takes seconds and a PDF page does not.

Generate for Existing Files¶

For STL and PDF files already in your library, click Generate Thumbnails in the toolbar. It renders every STL and PDF file that has no thumbnail yet, in all folders, and the new thumbnails appear in the grid once the run is finished. A toast reports how many succeeded and failed.

With library:update_all the run covers everyone's files. With only library:update_own it covers the files you uploaded yourself.

Single File Generation¶

Generate a thumbnail for one file:

1. Find the STL or PDF file
2. Click the three-dot menu ()
3. Select Generate Thumbnail
4. The thumbnail updates automatically when done

ZIP Extraction with Thumbnails¶

When extracting ZIP files containing STL files:

1. Upload a ZIP file
2. Check Generate thumbnails for STL files
3. Thumbnails are created for all STL files in the archive

PDF files inside the archive are thumbnailed as well, checkbox or not.

Technical Details¶

PDF, STEP and spreadsheet thumbnails¶

PDF files get a thumbnail of their first page as soon as they enter the library: on upload, inside an extracted ZIP, and when an external folder is scanned. Generate Thumbnails in the toolbar also covers PDFs, so ones added before this existed can be backfilled in one go. A PDF that cannot be read (damaged, password-protected) simply has no thumbnail until it is opened.

STEP (.step, .stp) and spreadsheet (.csv, .xlsx, .ods) files have no server-side renderer. Their thumbnail is taken from the first time someone opens the file's preview, and is saved for everyone from then on.

Document, Image & CAD Previews¶

Beyond the printable formats, the File Manager can preview the other files a real job folder tends to contain — source geometry, drawings, part lists and reference photos — without downloading them (#2976):

Printable files have a preview too: .stl and source .3mf open the 3D viewer, and a sliced file (.gcode, .gcode.3mf) opens the full-page G-code viewer.

TIFF files (.tiff, .tif) get a thumbnail on their card, but no preview: browsers other than Safari cannot display them, so the file has to be downloaded to be looked at.

Opening a preview¶

There are three ways, and they all open the same thing:

• Double-click the file — on its card in grid view, or on its row in list view. A file with no preview simply does nothing.
• The Preview button in the toolbar above the file list, which appears as soon as exactly one previewable file is selected.
• The file's own menu: the three-dot menu () on the card in grid view, or the preview icon in the trailing actions column in list view.

Previewing needs the same library:read_own / library:read_all permission as downloading the file.

Fullscreen and zoom¶

Every preview opens in one large window — as wide as the screen allows, up to 1800 px — with a fullscreen button in its header, and a double-click on the preview area toggles fullscreen too. Esc leaves fullscreen; press it again to close the preview. Where the browser does not allow fullscreen for page elements (iPhone Safari, some embedded views) the preview fills the browser window instead.

• PDF: Ctrl/⌘ + mouse wheel and trackpad pinch zoom around the pointer; on a touch screen, pinch with two fingers. The plain wheel zooms while the whole page is visible and scrolls once it is not. Keyboard: + / - step the zoom, 0 resets it. The zoom buttons remain.
• 3D viewer (STL, STEP): mouse wheel or pinch to zoom, drag to orbit, right-drag to pan, in the window and in fullscreen alike. The zoom range is bounded so the model can never be dollied out of view; Reset returns to the framed view.
• Images: the picture opens fitted to the window. The mouse wheel, a trackpad pinch and the + / - keys zoom around the pointer, 0 and the reset button go back to the fitted view, and once the picture is bigger than the window you can drag it around.

Thumbnails¶

• PDF: the first page is rendered on the server when the file is uploaded or extracted from a ZIP, and through the toolbar's Generate Thumbnails button — nobody has to open the file. PDFs found by an external folder scan are rendered in the background after the scan finishes, alongside the STL thumbnails, so they fill in over the following seconds. See STL and PDF Thumbnail Generation.
• Images are thumbnailed by the server as well, from the picture itself, on upload / ZIP extraction / external scan.
• STEP and spreadsheets are rendered in your browser — the server has no CAD kernel. The first time someone opens a preview, that first render is stored as the file's grid thumbnail (a STEP model's 3D view, a mini table for spreadsheets). Until then the grid shows a per-type icon. Persisting the thumbnail requires library:update_own / library:update_all; users without it still get the full preview, only the thumbnail is skipped. The same browser fallback covers a PDF the server could not render, as long as the browser can open it.
• A thumbnail that already exists is never replaced by a preview render.

Limits & fallback behaviour¶

• Spreadsheets over 20 MB, and PDFs and images over 50 MB, show a "too large to preview" notice instead of stalling the browser.
• Very large sheets are truncated in the view (first 500 rows / 40 columns, with a notice saying so) — scrolling covers the rest of the day-to-day cases; the preview is not an editor.
• A broken or unreadable file falls back to a short message in the preview and keeps its generic icon in the grid; nothing errors out. That includes password-protected PDFs, which the preview cannot unlock.
• STEP files are converted to a 3D mesh in your browser. A large export can take a minute or more; the preview shows Converting STEP model… with a running seconds counter while it works, so leave it open until the model appears.
• The preview libraries (OpenCascade WASM for STEP, pdf.js, SheetJS, PapaParse) are loaded on demand, so they add nothing to the app's initial load time.

Slice a file¶

Unsliced models carry a Slice action: in the file card's ⋮ menu, and as an icon in the trailing actions of the list view. It appears on source geometry only — .3mf, .stl, .step and .stp, narrowed to .3mf alone when the desktop handoff targets Bambu Studio (see the note below) — and never on a file that is already sliced, since sliced G-code is an output rather than an input. A .3mf that turns out to hold G-code counts as sliced here too, whatever it is called.

What the action does depends on whether you run the slicer sidecar:

Which desktop slicer receives the handoff comes from Settings → Workflow → Slicer → Open in Slicer, falling back to your Preferred Slicer when it is left on Same as API slicer.

Choosing a slicer from the 3D preview¶

Opening a model's 3D preview gives you the same action as a split button in the header: the left half runs the default described above, and the chevron on the right opens a short menu of the alternatives.

• With the sidecar off, the menu offers the slicer you did not set as your desktop target — a one-off handoff to the other one without changing any setting.
• With the sidecar on, the primary button slices server-side and the menu offers a desktop handoff to either slicer, so you can send a single file to a local GUI without turning the sidecar off.

The chevron is absent when the file cannot go to a slicer at all, in which case the button itself is disabled.

Print¶

Print files from File Manager with full configuration options.

Starting a Print¶

1. Find a sliced file (.gcode or .gcode.3mf)
2. Click the printer icon or right-click for context menu
3. Select Print
4. The print modal opens with:
5. Printer selection - Choose one or more printers
6. Plate selection - For multi-plate 3MF files, select which plate to print
7. Filament mapping - Map required filaments to loaded AMS slots
8. Print options - Bed levelling, flow calibration, timelapse, etc.
9. Dispatch option - ASAP, Queue, or Schedule
10. Click Print to submit the job to the scheduler

Multi-Printer Printing¶

Select multiple printers to send the same file to all of them at once—ideal for print farms.

Printing Alternatives for Different Printers¶

If you own printers that need different slices — an H2S and an H2C, say — select both sliced files and press Print. Instead of two competing queue items, you get one job that runs on whichever printer frees up first, using that printer's own file.

The print modal replaces the printer picker with the candidate list, ordered by preference. See Cross-Model Alternatives for the full behaviour.

To make the pairing permanent, select the files and choose Group as versions. Grouped files carry a N versions badge, and printing any one of them then offers the whole group without re-selecting. The count includes members stored in other folders.

Remove a file from its group, or drop the group entirely, without affecting the files themselves — each remains independently printable. A group that falls below two members is dissolved automatically, since one file is not a choice.

Queue Insertion¶

The Print modal adds sliced files to the queue without creating archives upfront.

How It Works¶

When you submit a library file through the Print modal:

1. The queue item references the library file directly
2. No archive is created until the print actually starts
3. This keeps your Archives clean. Only files that were actually printed appear there

Single File¶

1. Find a sliced file (.gcode or .gcode.3mf)
2. Click the printer icon or right-click for context menu
3. Select Print
4. Configure:
5. Printer - Select target printer(s)
6. Plate - For multi-plate files
7. Filament mapping - AMS slot configuration
8. Dispatch option - ASAP, Queue, or Schedule
9. Print options - All print settings
10. Click Print

Multiple Files¶

1. Select multiple sliced files (checkbox)
2. Click Print in the toolbar
3. Choose the printer and dispatch option
4. All files are submitted to the queue

Deleting Files¶

Deleted files move to the Trash. They stay there for a configurable retention window (default 30 days) before a background sweeper permanently removes them from disk, which gives you an undo window for accidental deletions.

Single File¶

1. Find the file
2. Click the delete icon
3. Confirm deletion — the file moves to the Trash

Multiple Files¶

1. Select files (checkbox)
2. Click Delete Selected
3. Confirm deletion — all selected managed files move to the Trash

Restoring or permanently removing trashed files¶

Open the Trash (button in the File Manager header) to see files you've deleted. Regular users see their own trashed files; admins see everyone's.

• Restore — moves the file back to its original folder
• Delete now — permanently removes the file from disk immediately, bypassing the retention window
• Empty trash — hard-deletes every trashed file in your scope

Admins can also change how long trashed files live on the Trash page itself (1–365 days, default 30).

Deleting Folders¶

Folders have no owner, so deleting a folder with contents (a cascade delete of everything inside) requires the library:delete_all permission.

Users with only library:delete_own can still delete empty folders — for example a folder they created and have since emptied out. "Empty" is strict: the folder must contain no subfolders and no files, including trashed files (a trashed file still belongs to whoever deleted it and must stay restorable). External folders and folders linked to a project or archive always require library:delete_all, even when empty.

The folder tree's Delete entry reflects this: on a non-empty folder it is disabled with a "You can only delete empty folders" hint.

Purge Old Files (admin)¶

For libraries that have grown into gigabytes, admins get a bulk Purge old action in the File Manager header. Pick an age threshold (e.g. "files not printed in 90 days"), see a live preview of how many files would move and how much disk that frees, then confirm.

What happens when you click Purge¶

• Matching files are moved to Trash — they are not deleted from disk yet.
• You can restore them from Trash at any time until the retention window expires.
• After retention, the trash sweeper permanently removes them from disk.
• Files in external (linked) folders are skipped — Bambuddy never deletes bytes it does not own.

Because files only move to Trash, the disk doesn't free up immediately. To reclaim the space right away, empty the Trash manually afterwards.

How "old" is measured¶

• Files with a print history → aged by their last-printed date.
• Files that have never been printed → aged by upload date, and only when the "Include files that have never been printed" checkbox is on (default). Turn it off to limit the purge to files you've actually printed before.

The "Purge old" button only appears for users holding the new library:purge permission, which ships enabled by default on the built-in Administrators role. To grant it to an Operator role, add library:purge in Settings → Users → Groups.

Auto-purge (optional)¶

Don't want to remember to run the purge every month? Settings → File Manager → Auto-purge old files runs the same operation automatically once per 24 hours:

• Age threshold (minimum 7 days, maximum 10 years) — uses the same rule as the manual button
• Include-never-printed checkbox
• Default off; opt-in only so existing installs aren't surprised

Auto-purge still respects the trash retention window — files are moved to Trash first, not deleted outright. The sweeper later hard-deletes them after the retention period. The 24-hour throttle means the setting is safe even though the underlying sweeper ticks every 15 minutes.

Renaming Files & Folders¶

Rename files and folders directly in the File Manager.

Renaming a File¶

Grid View:

1. Hover over the file card (on a touch device its actions are always visible)
2. Click the three-dot menu ()
3. Select Rename
4. Enter the new name
5. Click Rename to save

List View:

1. Find the file in the list
2. Click the pencil icon () in the actions column
3. Enter the new name
4. Click Rename to save

Renaming a Folder¶

1. Hover over the folder in the sidebar (on a touch device its actions are always visible)
2. Click the three-dot menu ()
3. Select Rename
4. Enter the new name
5. Click Rename to save

File Details, Notes & Photos¶

Every library file can carry three things beyond the file itself: free-text notes, one external link (the Printables or Thingiverse page it came from, say) and photos of the printed result — the same trio an archive carries (#3077). All three are Bambuddy-side metadata: they live in Bambuddy's database and data directory, and nothing is written into the file or next to it.

Opening the details¶

Grid view:

1. Hover over the file card (on a touch device its actions are always visible)
2. Click the three-dot menu ()
3. Select File details

List view:

1. Find the file in the list
2. Click the info icon () in the actions column

Opening the details takes the same permission as previewing the file (library:read_own or library:read_all); without it the entry is disabled with a tooltip saying so. Editing follows the same rule as Rename: library:update_own for your own files, library:update_all for everyone's. Without it the modal is read-only — the fields are greyed out and neither the Add photo tile nor the Save button appears.

What the modal shows¶

The header carries the filename and its type badge. Below it come a read-only block of facts, then the three editable parts.

Notes — a free-text box (placeholder Print settings, tips, what worked...). Whatever you want to find again next time you print this file: the profile that finally worked, a support tip, which nozzle.

External link — one URL, e.g. https://printables.com/model/.... It must start with http:// or https://; the server rejects anything else, since the link is rendered clickable for everyone who can see the file. Once a link is entered, an Open link button next to the field opens it in a new tab. Clear the field to remove the link.

Notes and the link are written together when you click Save — the button only enables once something has changed, and a File details saved toast confirms the write. Close, or Esc, discards unsaved edits to those two fields.

Photos — thumbnails of the photos already attached, plus a dashed Add photo tile:

• Click Add photo and pick an image: .jpg/.jpeg, .png or .webp, up to 10 MB, one at a time. The upload happens immediately — photos do not wait for Save.
• Hover a thumbnail and click the red Delete photo button to remove it. That is immediate too, with no confirmation.
• Click a thumbnail to open the gallery on that photo: a full-screen lightbox with previous / next arrows (or the ← / → keys), a thumbnail strip when there is more than one photo, a Download button for the photo on screen, and a delete button that does ask for confirmation. Esc closes the gallery and leaves the details modal open behind it, unsaved edits and all.

Viewers without edit permission see the same photos and gallery, minus deleting, and No photos yet when there are none.

Indicators in the file list¶

Once a file carries any of the three, small indicators appear on it so you can tell at a glance without opening the modal:

On the card the indicators sit under the print count; in the list they follow the filename. A file with a link also gains an Open link entry in its three-dot menu, so the link is one click away from the card as well.

External folders and folders¶

Where photos are stored¶

Photos live in Bambuddy's library data directory, under archive/library/photos/<file id>/, with generated names — the file's record only holds the list. Since the whole archive/ tree goes into a backup, so do they.

They leave the disk together with the file: when a trashed file is purged — by Delete now, Empty trash or the retention sweeper (see Deleting Files) — and immediately when a file that bypasses the Trash, such as an external file, or a whole folder is deleted. A scan of an external folder that finds the file gone from the share drops its entry the same way, photos included. Moving a file to the Trash does not touch its photos; restore it and they are back.

One flow moves them rather than deleting them. A file dropped straight onto a printer card (see Drag & Drop) is consumed by the print it was uploaded for: once the job is dispatched, Bambuddy replaces the library entry with the archive of that print. The photos go across with it and are on that archive afterwards, in its own photo gallery.

External Folder Mounting¶

Mount host directories (NAS shares, USB drives, network storage) into the File Manager without copying files.

Setting Up an External Folder¶

Step 1: Bind-mount the directory into Docker

Add the host directory as a volume in your docker-compose.yml:

services:
  bambuddy:
    volumes:
      - /mnt/nas/3d-prints:/external/prints:ro

Restart the container after changing volumes.

Step 2: Link the folder in Bambuddy

1. Open File Manager
2. Click Link External in the toolbar
3. Enter a display name (e.g., "NAS Prints")
4. Enter the container path (e.g., /external/prints)
5. Choose options:
   • Read Only (default) — prevents uploads and deletions
   • Show hidden files — includes dotfiles in scan
6. Click Link Folder

The folder is automatically scanned and files appear immediately.

Scanning & Refreshing¶

External folders are indexed on creation. To pick up new or removed files:

1. Click on the external folder in the sidebar
2. Click the Scan button in the info bar
3. New files are added, deleted files are removed from the index

Read-Only Protection¶

When Read Only is enabled (default):

• Uploads to the folder are blocked (403)
• Moving files into the folder is blocked
• ZIP extraction to the folder is blocked
• Files can still be downloaded, printed, and queued

Deleting External Folders¶

When you delete an external folder from Bambuddy:

• The database index is removed
• Generated thumbnails are cleaned up
• The actual files on disk are never deleted

Linking Folders¶

Link folders to projects or archives for organization:

Creating Links¶

1. Hover over an unlinked folder
2. Click the link icon that appears
3. Choose to link to a Project or Archive
4. Select the target from the dropdown
5. Folder shows a colored badge when linked

Managing Links¶

• Click the badge on a linked folder to change/remove the link
• Or use the context menu (right-click)

Link Benefits¶

• Quick navigation to related projects
• Visual organization with color-coded badges
• Group related files together

Refreshing¶

Manual Refresh¶

Click Refresh to reload the file list.

Auto-Refresh¶

File list updates when:

• You navigate directories
• After delete operations
• After adding files to queue

Safety¶

Before Deleting¶

• Ensure files aren't needed for queued prints
• Download backups of important files first
• Deleted files cannot be recovered

API Access¶

Access library files programmatically:

# List files
GET /api/v1/library/files

# Get file details
GET /api/v1/library/files/{id}

# Upload file
POST /api/v1/library/files/upload

# Extract ZIP file
POST /api/v1/library/files/extract-zip

# Add to queue (optionally: "printer_id" or "target_model" for the whole batch)
POST /api/v1/library/files/add-to-queue

# Delete file
DELETE /api/v1/library/files/{id}

# Create external folder
POST /api/v1/library/folders/external

# Update notes / external link (#3077)
PUT /api/v1/library/files/{id}

# Photos of the printed result (#3077)
POST /api/v1/library/files/{id}/photos
GET /api/v1/library/files/{id}/photos/{filename}
DELETE /api/v1/library/files/{id}/photos/{filename}

# Scan external folder
POST /api/v1/library/folders/{id}/scan

See API Reference for details.

Mobile & PWA Support¶

The File Manager is optimized for touch devices and the PWA (Progressive Web App).

Touch-Friendly Interface¶

• Action buttons are always visible on any device without a mouse — phone or tablet, whatever the screen width — since there is no hover to reveal them with. This covers folder actions in the sidebar as well as the file cards.
• Selection checkboxes appear on all file cards for easy multi-select
• Context menus accessible via the three-dot button on each card
• Responsive grid adjusts columns based on screen size

PWA Tips¶

• Add Bambuddy to your home screen for a native app experience
• File Manager works offline for browsing cached files
• Swipe gestures work naturally on touch devices

Tips¶