Watch
1
0
Fork
You've already forked BenchVault
0
No description
  • Rust 67.5%
  • TypeScript 30.6%
  • Shell 0.9%
  • Makefile 0.6%
  • CSS 0.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-07 23:14:22 +01:00
.claude Ignore and deny reading env files 2026-07-17 21:33:17 +02:00
demo/docker Expand the folder tree and pick a lighter STL for the screenshots 2026-07-22 22:03:27 +02:00
docs Document the MCP server, Hide-from-AI flag and remaining follow-ups 2026-11-07 23:14:22 +01:00
public Add the application, desktop and mobile icon sets 2026-05-09 22:49:54 +02:00
scripts Self-extract linuxdeploy to avoid FUSE mount failure 2026-07-21 23:16:52 +02:00
src Add Hide-from-AI private flag and embedded MCP server 2026-11-07 23:14:22 +01:00
src-tauri Add Hide-from-AI private flag and embedded MCP server 2026-11-07 23:14:22 +01:00
.env.local.example publish packages to codeberg 2026-07-16 22:06:15 +02:00
.gitignore Ignore and deny reading env files 2026-07-17 21:33:17 +02:00
AGENTS.md Add AGENTS.md pointing to CLAUDE.md 2026-07-17 21:33:56 +02:00
BACKLOG.md Document the MCP server, Hide-from-AI flag and remaining follow-ups 2026-11-07 23:14:22 +01:00
CLAUDE.md Document the MCP server, Hide-from-AI flag and remaining follow-ups 2026-11-07 23:14:22 +01:00
index.html Disable webview zoom (ctrl+wheel, ctrl +/-/0, pinch) 2026-11-07 23:14:22 +01:00
Makefile Makefile: pin install-host to the current version's .deb 2026-11-07 23:14:22 +01:00
package-lock.json Add support for OBJ, STEP, CadQuery and Markdown files 2026-07-17 22:13:23 +02:00
package.json Bump version to 0.1.2 2026-07-22 23:29:45 +02:00
postcss.config.cjs Scaffold the Vite + React + TypeScript frontend 2026-05-08 21:31:39 +02:00
README.md Document the MCP server, Hide-from-AI flag and remaining follow-ups 2026-11-07 23:14:22 +01:00
tsconfig.json Scaffold the Vite + React + TypeScript frontend 2026-05-08 21:31:39 +02:00
tsconfig.node.json Prepare the repo for publishing 2026-07-16 21:18:40 +02:00
vite.config.ts Prepare the repo for publishing 2026-07-16 21:18:40 +02:00

Mirrored on GitHub — development happens here: https://git.hauptstadt.monster/manzari/BenchVault

BenchVault

A cross-platform (Linux-first) desktop app for organizing 3D-printing projects. Each Object groups the STL parts, OpenSCAD sources, sliced gcodes, images, and notes that belong to one thing you print — with slicer metadata parsed automatically and everything searchable.

BenchVault owns a managed library on disk (human-readable folder layout), so your files stay plain files you can browse, back up, or take with you.

Screenshots

Library overview

Object detail with STL preview

Regenerating these screenshots

make shots builds a throwaway demo library inside Docker (your real library is never in reach) and drives the actual binary through tauri-driver to capture docs/screenshots/.

The demo library is seeded by importing real things from Thingiverse through the same "Import from URL" code path the app ships, so the screenshots show genuine models, covers, authors and licenses rather than placeholder geometry. That needs a Thingiverse API token:

  1. Create an app at https://www.thingiverse.com/developers/apps (any type — you only need its App Token).

  2. Put it in the repo-root .env, which is gitignored:

    THINGIVERSE_TOKEN=your-app-token
    

make shots picks it up from there and passes it into the container; the seeder clears it from the demo database again once the imports are done. Same token works for the app's own "Import from URL" — paste it into Settings.

make build      # release binary
make seed-bin   # demo seeder
make shots      # seed + capture into docs/screenshots/

Workflow

BenchVault sits at the centre of a print project — from CAD source to a printed part — keeping every artifact filed against the Object it belongs to.

flowchart LR
    A["<b>Design</b><br/>OpenSCAD · FreeCAD ·<br/>Blender · any 3D tool"] -->|export STL| B
    B["<b>BenchVault</b><br/>organize into an Object:<br/>models · CAD scripts ·<br/>images · docs · tags"]
    B -->|open .scad in GUI /<br/>render preview| A
    B -->|slicer hand-off| C["<b>OrcaSlicer</b><br/>slice → gcode"]
    C -->|auto-ingest gcode<br/>+ parsed metadata| B
    B -->|USB sync<br/>+ manifest| D[("<b>USB drive</b>")]
    D --> E["<b>3D printer</b><br/>print the part"]

    classDef hub fill:#2b6cb0,stroke:#1a365d,color:#fff;
    class B hub;
  1. Design a part in OpenSCAD (or FreeCAD, Blender, …) and export an STL — or import from a URL (Thingiverse, a GitHub/GitLab/Codeberg repo, MyMiniFactory).
  2. Organize it in BenchVault: models (STL/OBJ/STEP/3MF), CAD scripts (.scad, CadQuery .py), images, markdown docs and notes all live under one Object. Open .scad files back in the OpenSCAD GUI or render previews in-app.
  3. Slice by handing an asset straight to OrcaSlicer; the resulting gcode is auto-ingested with its slicer metadata parsed.
  4. Sync the gcodes to a mounted USB drive with a manifest.
  5. Print — feed the USB stick to the printer.

Features

  • Library organization — nested folders, objects with cover images, tags, manual sort order, breadcrumb navigation.
  • 3D preview — interactive three.js viewer for STL and OBJ; snapshot any angle as the object's cover image.
  • Model geometry — triangle/vertex counts, bounding-box size, volume, surface area, and watertightness computed on import for STL, OBJ, and 3MF; 3MF also carries its declared units, document metadata, and an embedded thumbnail that auto-fills the object cover.
  • Docs & CAD scripts — keep markdown notes (rendered as GitHub-flavored markdown) and CadQuery/OpenSCAD scripts filed alongside the part.
  • Gcode metadata — slicer, profile, print time, filament usage parsed on import. Supports the PrusaSlicer family (PrusaSlicer, SuperSlicer, OrcaSlicer, BambuStudio) and Cura.
  • OpenSCAD support — open .scad sources in the OpenSCAD GUI, render previews via the OpenSCAD CLI (cached on disk), and see extracted customizer parameters, dependencies, and module/function names in the CAD Scripts list.
  • Slicer hand-off — open assets directly in OrcaSlicer.
  • Import from URL — one field, source auto-detected from the link:
    • Thingiverse — title, author, license, and cover image; with an API token the model files are downloaded too.
    • Git hosts — GitHub, GitLab, or Codeberg repositories (or a /tree/<branch>/<folder> subfolder link) are downloaded and every model/gcode/image inside is parsed into the object; any other .git URL is cloned. Optional per-host tokens unlock private repos.
    • MyMiniFactory — title, author, license, and cover image via an API key (file downloads require their OAuth login, not yet supported).
  • USB sync — detect mounted drives and sync gcodes to them with a manifest, for printers fed by USB stick.
  • Auto-ingest — a background watcher picks up files dropped into the library directory and files them automatically.
  • Full-text search — SQLite FTS5 across the library.
  • AI access (MCP) — an optional local MCP server lets Claude Code (or another MCP client) browse, search and, if you allow it, organize the library. Folders and objects marked Hide from AI are left out. See AI access (MCP).

Supported formats

Everything you import is stored as a plain file in the managed library. The table shows what BenchVault does beyond storing it — parse metadata, preview in 3D, render, or hand off to the slicer.

Format Stored Metadata Preview Render Hand-off
STL (.stl) ✅ ✅ geometry ✅ — ✅ to orca
OBJ (.obj) ✅ ✅ geometry ✅ — —
3MF (.3mf) ✅ ✅ — — ✅ to orca
G-code (.gcode, .gco, .g) ✅ ✅ — — ✅ to usb drive
G-code binary (.bgcode) ✅ — — — ✅ to usb drive
OpenSCAD (.scad) ✅ ✅ static ✅ via render ✅ —
CadQuery (.py) ✅ — — — —
Markdown (.md, .markdown) ✅ — ✅ via render ✅ —
Text (.txt) ✅ — ✅ verbatim — —
CAD / STEP (.step, .stp, .iges, .igs, .f3d, .sldprt) ✅ — — — —
Images (.png, .jpg, .jpeg, .webp, .gif, .bmp, .svg) ✅ — ✅ some formats — —
Anything else (.pdf, .zip, …) ✅ — — — —

Models (STL/OBJ/STEP/3MF) share one Models section; STL and OBJ render directly in the in-app 3D viewer, while STEP and 3MF are stored and listed (3MF still gets its geometry and metadata parsed on import). OpenSCAD and CadQuery scripts share a CAD Scripts section (OpenSCAD sources also render to a previewable mesh, and their parameters/dependencies are listed). Markdown files render as formatted notes in a Docs / Notes section, and plain .txt files render verbatim there too. Images double as object cover art (snapshot the 3D viewer, set any imported image, or let a 3MF's embedded thumbnail fill in). STL parts are the only assets sent to OrcaSlicer.

AI access (MCP)

BenchVault can run an MCP server inside the app, so an AI assistant such as Claude Code can look through your library and, if you allow it, organize it. The server is off until you turn it on.

Hide from AI

Any folder or object can be marked Hide from AI. Hidden items never appear in anything the MCP server returns: listings, search results, tags, file contents. Asking for a hidden item by id gives the same "not found" error as an id that doesn't exist. The app itself is unchanged; you still see and edit everything.

  • Folders: click the robot icon on the folder's row in the library sidebar. A lock icon marks a hidden folder.
  • Objects: use the Hide from AI switch under AI access in the object's sidebar. Hidden objects get a lock next to their name and a "Hidden from AI" badge on their card.

Hiding is inherited. A hidden folder hides every subfolder and object inside it; those show a dimmed lock. Files follow their objects: a file attached to a hidden object is hidden, even if it is also attached to a visible one. Tags used only on hidden items are not listed.

Moving an object out of a hidden folder to a visible place asks for confirmation, because the object becomes visible. To keep it hidden, turn on its own Hide from AI switch before moving it; the switch stays usable while the object is hidden through its folder. Deleting a hidden folder keeps the subfolders and objects that drop to the root hidden.

Connecting Claude Code

  1. Open Settings → AI access (MCP) and turn on Enable MCP server. The first time, BenchVault creates an access token.

  2. Pick an access level (see below). The default is read-only.

  3. Copy the command from the card (it includes the token) and run it once in a terminal:

    claude mcp add --transport http benchvault http://127.0.0.1:<port>/mcp --header "Authorization: Bearer <token>"
    

The server speaks Streamable HTTP at http://127.0.0.1:<port>/mcp, port 47821 unless you change it. It listens on 127.0.0.1 only, every request needs the bearer token, and requests that carry an Origin header (that is, from web pages) are refused. Other MCP clients that support Streamable HTTP with a custom header can use the same URL and header.

Changing the port restarts the server. Regenerate replaces the token and the old one stops working at once. After either, update your client with the new URL or token. Changing the access level takes effect immediately, also for clients that are already connected. Turning the server off keeps the token. If the port is in use, the card shows "failed to start" with the error.

Read-only and read & write

Read-only (the default) offers seven tools:

Tool What it does
list_folders Every visible folder, with its path and object count
list_objects Pages through objects; filter by folder, root only, or tag
get_object One object: notes, source URL, author, license, tags, and its files with gcode or mesh metadata
search Full-text search over object names and notes, folder names and file names; name matches come first, then alphabetical (not ranked by relevance)
list_tags Tags in use on visible items, with counts
read_asset_text Text from the start of a markdown, text, OpenSCAD, CadQuery or gcode file (64 KiB by default, at most 1 MiB)
get_asset_image An image file, up to 5 MiB

Read & write adds eleven:

Tool What it does
create_folder, rename_folder, move_folder Create, rename and move folders
create_object, update_object, move_object Create objects, change their name, notes, source URL, author or license, and move them
add_tag, remove_tag Tag or untag an object
write_doc Replace the whole text of an existing markdown or text file
add_file_from_path Copy a file from your computer into an object
import_from_url Import a Thingiverse thing, MyMiniFactory object or GitHub, GitLab or Codeberg repository as a new object (https links only)

There are no delete tools; nothing can be deleted through MCP. The write tools can still overwrite things: update_object replaces fields (an empty value clears one), write_doc replaces a document's content, and remove_tag untags. The assistant can't see or change the Hide from AI flag, can't touch hidden items, and anything it creates is visible to AI. Its changes show up in the open app right away.

Limitations

  • The server only runs while BenchVault is open. Clients that can only launch a local stdio server (such as Claude Desktop's local config) can't connect yet.
  • Hide from AI only controls what the MCP server returns. Library files are plain, unencrypted files, and the database next to them holds every name and note. Both live in BenchVault's data directory (~/.local/share/dev.manzari.benchvault on Linux). An assistant that can read your filesystem directly can still read hidden items. If yours can, deny it read access to that directory. In Claude Code that is a deny rule such as Read(~/.local/share/dev.manzari.benchvault/**) in ~/.claude/settings.json. Such a rule covers Claude Code's file tools and the shell commands it recognizes, like cat, but not a script that opens files itself; for that, use Claude Code's sandbox.
  • With read & write access, add_file_from_path can copy any file your user account can read, given its absolute path, into the library, where the assistant can then read it. The file must have a supported extension (models, gcode, OpenSCAD, CadQuery, markdown/text, CAD, common images), be at most 100 MiB, and lie outside BenchVault's data directory.
  • With read & write access, import_from_url makes BenchVault download from the internet using the tokens and API keys saved in Settings. The credentials themselves are never returned to the assistant. It accepts only https links to Thingiverse, MyMiniFactory, GitHub, GitLab and Codeberg; other Git URLs (any .git link) can be imported from the app itself, not by the assistant.
  • If the assistant adds a tag whose name is used only on hidden items, BenchVault gives that tag a new id and the color the assistant asked for (or none), so it can't tell that hidden items use it. The hidden items keep the tag but lose its old color.

Stack

  • Tauri 2 — Rust backend + system webview
  • React 18 + TypeScript + Vite + Mantine 7 + TanStack Router + Zustand
  • SQLite via sqlx with versioned migrations and FTS5 search
  • three.js via @react-three/fiber for STL/OpenSCAD previews
  • specta + tauri-specta — TypeScript bindings generated from the Rust command signatures, so the IPC contract can't drift

Install

Build from source (see below) and install the resulting bundle, or on Debian/Ubuntu let the Makefile do both:

make install-host   # builds the .deb and installs it via apt

Prerequisites (building from source)

Install once on Linux:

# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Node (via your favourite manager — fnm shown here)
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 20

# Tauri system deps (Debian/Ubuntu)
sudo apt update
sudo apt install -y libwebkit2gtk-4.1-dev build-essential curl wget file \
  libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev

Optional integrations: OpenSCAD for .scad previews, OrcaSlicer for slicer hand-off. Both are auto-detected; paths can be overridden in Settings.

Develop

npm install        # or pnpm / bun
npm run tauri dev  # Vite + Rust with hot reload on both sides

The first launch creates <app_data>/library/ and benchvault.db, and runs all migrations.

make help lists the other targets (check, clippy, test, bindings, …).

Build

npm run tauri build

Produces .deb / .rpm / .AppImage on Linux. Windows/macOS targets build but aren't tested or gated by CI yet.

Architecture

The Rust backend follows a strict commands → service → repository → db layering; the frontend talks to it through generated typed bindings.

  • src-tauri/src/commands/ — thin Tauri command handlers
  • src-tauri/src/mcp/ — the embedded MCP server, a second front-end next to commands/ that may only call service::ai, the layer that applies Hide from AI
  • src-tauri/src/service/ — business logic (file ingestion, imports, USB sync, external tools)
  • src-tauri/src/repository/ — all SQL, one module per table family
  • src-tauri/src/parsers/ — pure gcode/STL parsers
  • src-tauri/migrations/ — versioned SQL, run automatically on start
  • src/ — React frontend
  • src/lib/bindings.ts — generated by specta (make bindings) — do not hand-edit

The schema is intentionally polymorphic (assets, tags + entity_tags, entity_links, one FTS5 index keyed by entity kind), so future entity types — printers, filaments, print jobs, slicer profiles, costs — drop in without re-architecting. See CLAUDE.md for the full contributor guide.