GETTING STARTED

Where your files live

A vault is a folder. Your originals are files. What you decided about them is text. The database is a cache. Here is what that looks like on disk.

The folder

~/Pictures/Studio/
  vault.json                      name, description, format version
  originals/
    3f/9c2a…e1.webp               an original, named by its content hash
    3f/9c2a…e1.webp.teserra       its sidecar: what you decided about it
  collections/
    sculpture.toml                a collection, with its parent and style
  thumbs/                         regenerable
  (cache, elsewhere)              the SQLite database, per machine

Originals are named by a hash of their content, so the same image never enters twice and a file can be found again even if renamed elsewhere. The sidecar keeps the original filename.

A sidecar

One TOML file per item, written atomically each time you change something. It holds the decisions: name, title, description, tags, rating, collections (by stable id), pins, source URL, the text read by OCR, an article's body, and a tombstone if the item is in the trash. Plus the file's identity: dimensions, format, dates. Anything a newer version writes that an older one does not know is preserved untouched.

name = "hand-sphere.webp"
title = "The sphere"
description = "A sculpted hand rises from a flat surface…"
tags = ["hand", "minimal", "sculpture"]
rating = 4
collections = ["c_7f3a"]
source = "https://teserra.app"
created = "2026-08-27T09:12:44Z"
updated = "2026-09-16T15:41:02Z"

The database is a cache

Teserra keeps a SQLite file per machine to make the grid fast. It is rebuilt from the folder: Settings → General → Rebuild from files reconstructs every item, collection and tag. Tested on a real vault: 826 items, 40 collections, 6,716 tag links back in under a second.

Sync and several Macs

Teserra watches the folder. Edit a sidecar by hand, drop files from another Mac, let iCloud, Dropbox or Syncthing sync: the grid follows within seconds. When two copies of the same sidecar arrive, tags and collections are merged, never lost; for the rest, the latest edit wins. Files iCloud has offloaded show a cloud badge and download when opened.

What this means. Back the folder up like any folder. Put it in git if you like. Open it in ten years with a text editor. Delete Teserra and lose nothing.
← License and MacsKeyboard shortcuts →