Skip to content

Theme Vault

Jump to bottom
Bobby Comet edited this page Aug 9, 2026 · 1 revision

Theme Vault Trust Model

Theme Vault is a discovery catalog backed by a manifest.json. It helps users find themes and then routes them toward installation in one of two explicit ways:

  1. Manual/external — open the theme’s own link (or use schema location hints) and obtain the files yourself, then import via Manager if needed.
  2. Community Store — when the theme is also published in a store index, use the Store tab’s download-and-install path (optional SHA-256).

Theme Vault itself never downloads theme archives and never installs them.

Core design rule

Theme Vault expands what users can find and navigate toward.
Community Store is the only catalog-backed path that downloads and installs.
Manager import is the local fallback for archives the user already has.

Every install path requires a deliberate user action.

What the Theme Vault manifest provides

The catalog is a static manifest.json (plus optional $ref’d theme JSON). Entries typically include:

  • Identity and metadata (id, name, author, version, description, tags, license, etc)
  • Media (preview, screenshots, readme/readme_url)
  • An outbound link to the theme’s real home (GitHub, Pling, openDesktop, KDE Store, etc)
  • Host labeling derived from that link
  • Schema fields that can point to a store location (so the UI can offer a “check the store” action for that entry)

Studio uses this data to:

  • Browse and filter themes
  • Show previews and safely rendered READMEs
  • Open the external link
  • Offer a button that checks the store at the location described in the schema (when present)

That button does not install. It directs the user toward the Community Store (or the relevant store UI) so they can decide whether to use the automated install path, or it reinforces the manual route when no store entry applies.

Installation routes after discovery

Route When to use it What Studio does
Community Store function Theme is published in a store index the user has configured Fetch index → download archive → optional SHA-256 check → install into ~/.config/conky/
Manual/external (via Theme Vault link or store-location button) Theme is only linked out, or user prefers the original host Open browser/store page; user downloads; user may later drop the archive into Manager
Manager zip/tar import User already has a local .zip / .tar.gz / .tgz / .tar (from Theme Vault guidance, a forum, USB, etc.) Extract with path-safety checks, optional minimal start.sh, fonts if present, install into ~/.config/conky/

Theme Vault’s job ends at “here is the theme and here is how to reach it.”
Community Store owns automated install for indexed packages.
Manager import owns “I already have this file.”

Trust boundaries

Layer Who is trusted Risk Mitigations
Theme Vault manifest.json Publisher of the catalog URL Misleading metadata, fake previews, bad links, or store-location hints You choose the catalog URL. Official defaults are project-controlled. The manifest is metadata only; no theme code is fetched for install.
“Check the store” /schema location Same publisher + whatever store host is indicated Points user at a store or page that is not what they expect Still only navigation. Install happens only if the user proceeds in the Community Store or downloads manually.
Community Store index Publisher of the Index URL Malicious or swapped archives Prefer indexes that publish sha256. Mismatch aborts install. Only point the index URL at sources you believe.
Local archive (Manager import) You + whoever supplied the file Unsafe paths, unexpected scripts, malicious Lua once started Extractor rejects path traversal. No content audit. Running the theme has normal user privileges.
Running theme You + theme author Shell/Lua under your account Same as any Conky theme. Prefer known authors; inspect when it matters.

A Theme Vault listing is not an install endorsement.
A Community Store listing is an explicit “this index offers this archive for install.”
A Manager drop is the user asserting “install this local file.”

Practical guidance

  • Use Theme Vault to discover themes, read metadata/READMEs, and follow links or the store-location action.
  • Prefer the Community Store function when the theme is available there, especially when the index includes SHA-256.
  • Use Manager import for archives you obtained outside the store (including after a Theme Vault link-out or manual download).
  • Treat every running theme’s start.sh and Lua as code that runs with your user privileges.

Design philosophy

  • Theme Vault stays a pure catalog plus navigation helpers (including “check the store” from schema location fields).
  • Community Store is the curated, index-driven download-and-install path.
  • Manager import remains the general local-archive tool for everything else.
  • The user always chooses before any third-party theme code is written under ~/.config/conky/ and before it is started.

That separation is the trust model.

Clone this wiki locally