PrintStash is a local-first web app for STL, 3MF, OBJ, and G-code libraries. Upload manually or let OrcaSlicer push new G-code after every slice, then find files by model name, collection, tags, slicer metadata, material, printer, and print history.
Quick Start · Features · Comparison · Wiki / Docs · Limitations · Security
PrintStash is an early open-source, self-hosted project. The current release is usable for local libraries and Moonraker/Klipper workflows, with Docker Compose as the primary install path. SQLite plus local disk is the default; Postgres and S3/R2-compatible storage are optional.
Hardware reports, parser fixtures, install notes, docs fixes, and UX feedback are welcome in Discussions or issues.
Ingest and organize
- STL, 3MF, OBJ, STEP/STP, and G-code upload from the browser.
- URL imports and
.ziparchives, with per-file selection on extraction. - An OrcaSlicer post-processing hook pushes exported G-code automatically: it logs in with username + API key, then uploads under a JWT Bearer token.
- Content-hash dedup groups files into logical models and keeps version history in one place rather than scattered across folders.
- Nested collections, flat tags, search, filters, thumbnails, grid/list views, sorting, breadcrumbs, and drag-and-drop between collections.
Shared volumes (mirror a folder or NAS)
- Point PrintStash at a folder on the server or a NAS and it indexes files in place — no copying, no second source of truth; only thumbnails and metadata are stored in the vault.
- Two-way sync: scans pick up added, removed, and edited files, and web uploads and revisions write back into the folder (never overwriting existing bytes).
- Keep it current with a per-volume schedule (presets or custom cron), manual "Scan now", and optional real-time watching of local folders.
- Network folders (NFS/SMB) can't deliver filesystem events, so watching auto-detects the filesystem and falls back to the schedule — with a per-volume override. An unmounted share can never trigger a mass delete.
Preview and inspect
- A browser 3D viewer for source meshes — solid, X-ray, and wireframe modes, plus build-plate grid, fit-to-view, zoom, reset, and screenshot.
- G-code toolpath preview with layer navigation, travel visibility, and bed overlays derived from printer profiles.
- One model detail page covers the source files, recommended G-code, slicer settings, mesh metadata, and print history.
- Slicer metadata is parsed out of common OrcaSlicer, PrusaSlicer, Bambu Studio, Cura, and Klipper-style output: slicer/version, printer profile, nozzle, layer height, infill, material, filament brand/type, temperatures, estimated time, and filament length/weight/cost.
- Mesh metadata where the file carries it — bounding box, volume, triangle count.
G-code revisions
- Multiple G-code revisions per model, each with a label, notes, and outcome status.
- Statuses are
known_good,needs_test,failed, orarchived; exactly one revision is recommended at a time. - A side-by-side compare view diffs two revisions on slicer, material, and print metadata.
- The first successful print auto-marks a revision known-good.
Printer workflows
- Moonraker/Klipper printers with live WebSocket status and send-to-print.
- Remote file inventory sync, matched back to vault files where the filenames line up.
- Vault-initiated jobs track through upload/start/status states, and the UI shows which printer already holds a model's G-code or can start a supported remote file.
- Print history import pulls measured filament use, actual duration, and per-print cost from Moonraker.
- Provider diagnostics cover capabilities, configuration, and connectivity.
- Bambu LAN status and pause/resume/cancel, in beta.
- Optional Spoolman integration (OFF by default): show spool inventory, pick a spool per print, and decrement it by the real grams used on a Moonraker-measured completion — with double-count detection for Moonraker's native Spoolman hook.
Statistics and cost insights
- A Statistics dashboard (admin-only) turns completed prints into trends: total cost, prints, filament used, average filament per print, and total print time.
- A cost / filament / prints time series with selectable area, line, or bar charts, plus top collections and most-used filaments breakdowns.
- Period filter (7/30/90 days, 1 year, all time) and a configurable display currency (Settings → Design) applied across cost figures.
Users, access, and administration
- A first-run setup wizard creates the first admin account. There is no default password.
- JWT login with refresh/logout, admin user management, and named API keys for scripts and slicer hooks.
- Collection-level RBAC shares parts of a library at view/edit/admin levels.
- Audit logs record who changed what.
- A recycle bin keeps soft-deleted models restorable until retention expires, with manual restore, purge-expired, and permanent-delete.
Backups, portability, and customization
- Full backup/restore of the database plus stored files and thumbnails.
- Backups can mirror to S3/R2-compatible storage, independent of where vault files live.
- Metadata export to JSON or CSV for analysis, migration planning, or audits.
- Model-card metrics and the metadata fields shown on detail pages are configurable.
- Local disk by default, with optional S3/R2 object storage and Postgres, plus upload limits, trash retention, and backup retention.
- Health checks report database, storage, backup, and printer-provider readiness.
Warning
Run PrintStash only on a trusted self-hosted network. Do not expose it
directly to the public internet. If you need remote access, put it behind a
reverse proxy with TLS and your own authentication, and change
VAULT_JWT_SECRET from its placeholder default first.
See Security.
Requirements: Docker and Docker Compose. Prebuilt images are published for
linux/amd64 and linux/arm64 (Raspberry Pi 4/5, ARM NAS, Apple-silicon VMs).
On ARM, STEP/STP files upload and store but don't get a 3D preview — see
Known Limitations.
A modest host is enough. As a starting point:
| Resource | Minimum | Comfortable |
|---|---|---|
| RAM | 1 GB | 2 GB+ |
| CPU | 1 core | 2+ cores |
| Disk | ~1 GB for images | + room for your library |
SQLite + local disk is the default; thumbnailing large meshes is the most memory-hungry step, so give it 2 GB if you upload big STLs. Storage grows with your library — the files themselves dominate, the database stays small.
The default docker-compose.yml pulls prebuilt images from GHCR — no build step.
git clone https://github.com/xiao-villamor/PrintStash.git
cd PrintStash
cp .env.example .env
# Edit .env and set a strong, random value for VAULT_JWT_SECRET,
# e.g. `openssl rand -hex 32`.
docker compose up -dFor a hardened production setup (API kept internal, frontend bound to localhost behind your own TLS reverse proxy), use the production compose instead:
docker compose -f docker-compose.prod.yml up -dTo build the images from source instead of pulling (contributors), layer the
build overlay: docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build.
Pin a version for reproducible deploys. The compose files read
PRINTSTASH_VERSION (the image tag); set it in .env and bump it to upgrade:
echo "PRINTSTASH_VERSION=0.6.4" >> .env # pin; omit to track latestBy default the compose files track latest. Pin PRINTSTASH_VERSION when you
want deliberate upgrades. See Upgrading.
Open:
| Service | URL |
|---|---|
| Web UI | http://localhost:3000 |
| API docs | http://localhost:8000/docs |
| Health check | http://localhost:8000/api/v1/health |
On first launch, the web UI creates the first admin account. There is no default username or password.
| Asset grid | Search | Collections & filters |
|---|---|---|
 |
 |
 |
| Overview | 3D viewer | G-code toolpaths |
|---|---|---|
 |
 |
 |
| G-code revisions | Live printer status | Printer files | Printer diagnostics |
|---|---|---|---|
 |
 |
 |
 |
| Overview | Users & access | Storage | Design |
|---|---|---|---|
 |
 |
 |
 |
| Compare G-code revisions | Filter by tag |
|---|---|
 |
 |
PrintStash is a beta self-hosted release. It is useful today, but it is deliberately not a full manufacturing platform. Set expectations accordingly:
- Bambu LAN is beta and limited to local status plus pause/resume/cancel. Upload, send-to-print, remote file inventory, and remote-file start are not implemented for Bambu yet, issues are wellcome. Moonraker/Klipper is the fully supported provider.
- Hardware coverage is still thin. Provider behavior needs more real-world validation across printers, firmware versions, and network/auth setups. Reports are very welcome.
- Slicer metadata parsing varies. Extraction is best for common OrcaSlicer, PrusaSlicer, Bambu Studio, Cura, and Klipper output; missing fields are expected — please report them with safe sample files.
- The G-code viewer is a visualization aid, not a slicer-grade simulator. It does not validate firmware macros, acceleration, pressure advance, or safety.
- Not for direct public exposure. It is designed for trusted self-hosted networks (see Security).
- ARM has no STEP preview. Images run on
linux/amd64andlinux/arm64, but the OpenCASCADE tessellation dependency ships no Linux ARM wheel, so on ARM STEP/STP files upload and store without a generated 3D preview. All other file types and features are identical across architectures.
Full detail — including non-goals — lives in docs/known-limitations.md.
Bug reports, hardware notes, docs fixes, and small PRs are welcome. Start with CONTRIBUTING.md. Good first contributions include printer reports, parser fixtures, install notes, and small UI workflow improvements.
Not sure where to start? See community starter issues or open a discussion.
Read SECURITY.md before reporting vulnerabilities.
PrintStash is designed for trusted self-hosted networks; do not expose it
directly to the public internet without a reverse proxy, TLS, and your own
access controls. The production compose (docker-compose.prod.yml) binds only
the frontend to 127.0.0.1; copy-pasteable Caddy / Traefik / nginx examples are
in Reverse proxy with TLS.
PrintStash is licensed under the GNU AGPL-3.0.