steward · a file index service for Linux applications

What steward does

Many programs on a desktop walk the same directories over and over: the disk-usage viewer, the file search tool, the backup tool, the photo library, the deduplicator. Each builds its own partial, soon-stale picture. steward does the walking once, keeps the result current, and lets every application ask.

Layer 1

The index

Every path under your roots with its lstat fields, plus subtree totals for each directory: size, space on disk, file and directory counts. Name search like locate, and disk usage like qdirstat, from one index.

Layer 2

Classification

What things are: git repositories, ignored build output, dependency folders, virtualenvs, caches and trash, plus a category for each file (image, video, audio, document, source, archive…).

Layer 3

Content ids

A content id for each file: the BitTorrent v2 (BEP 52) Merkle root. It names bytes, not paths, so it survives renames and moves, finds duplicates anywhere, and matches the id other software computes for the same bytes.

Install

One command, no root, Linux on x86_64 or ARM64:

curl -fsSL https://toppk.github.io/steward/install.sh | sh
steward service install      # run the daemon now and at every login

The script downloads the latest release for your machine, verifies its SHA-256 checksums and installs steward (and, on desktops, steward-ui) into ~/.local/bin. It says whether it installed, upgraded or found the same version already there. It never replaces a program that isn’t steward, and doesn’t touch your shell configuration. Later, steward upgrade does the same and restarts the daemon.

Prefer to look first? Read install.sh, or download a binary from GitHub Releases (steward_linux_amd64 and its .sha256, for example), check it with sha256sum -c, make it executable and put it on your PATH. Getting started covers configuration and building from source.

What it promises

steward only reads what it indexes. It never creates, modifies, moves or deletes your files. The only things it writes are its own index, its sockets, its settings file when you change settings through it, and export files you ask for (which it will not overwrite).

Unplugged is not deleted. When a disk is unmounted, everything that was on it is reported offline, not gone. Nothing is dropped, and nothing is rescanned as if 600,000 files had vanished.
Identity follows the bytes. A renamed or moved file keeps its content id without being read again. A file whose bytes change loses it.
Applications get capabilities, not control. Applications talk to content.socket, which offers lookups and content primitives. Changing what is indexed, or how, is administration, on a separate socket.
No inotify. steward keeps up with periodic scans that skip unchanged directories, and with applications telling it what they changed. That scales to tens of millions of files with no kernel watch limits.

How it fits together

File manager

Disk usage viewer

Photo library

Your application

JSON-RPC 2.0 over Unix sockets

content.socket lookups · resolve · inspect · verify · events

api.socket roots · scans · settings · maintenance

steward daemon scheduler · scanner · classifier · hasher

index SQLite format, via turso

settings.toml your roots and their policies

The daemon (steward daemon) runs as your user, as a systemd user service, at low CPU and I/O priority. The rest of the steward command and the steward-ui desktop app are clients like any other.

Who this documentation is for

People running steward

Getting started, Configuration, the command line and the desktop app.

Application developers

Building on steward explains the patterns. The API reference lists every method, result and event.

AI agents

For AI agents is a compact operating guide. Every page is also available as Markdown, and llms.txt indexes them.

A first look

Once it is installed and running:

steward status                     # roots, scans, hashing, activity
steward tree ~ -d 2                # where the space goes
steward locate '*.iso'             # find by name, from the index
steward inspect ~/Downloads/film.mkv   # its content id, now
steward dups ~                     # identical files, most wasted space first

On the author’s machine, a first scan of a 15.7-million-entry home directory takes about a minute and a half. A daily rescan of an unchanged /usr takes 69 ms, and the daemon runs in about half a gigabyte of memory.