Look at a folder
Walks it and prints the totals. Nothing is stored, nothing is changed.
$ spacetrace scan ~/projects
scanned 84,213 entries in 1.9s
total 12.4 GiB logical · 12.7 GiB on disk
3 paths could not be readThe same scanner, in your terminal
Everything the app does, as a command you can script. Plus an agent that scans on a schedule, so a machine you never log into can still tell you what happened to its disk.
Install
curl -fsSL https://raw.githubusercontent.com/unalcakir28/spacetrace/main/install.sh | shInstalls spacetrace and spacetrace-agent into /usr/local/bin. Deliberately boring POSIX sh, because it also has to run on NAS firmware whose shell is busybox.
On Windows, unzip the archive and put spacetrace.exe on your PATH. There is no installer for the command line tool.
The four commands you will actually use
Keep the result
Stores the scan as a snapshot in a plain SQLite file, with a label if you want one.
$ spacetrace scan /srv --save --label weekly
saved snapshot #1Ask what changed
Compares the last two snapshots of a root, or the newest one against the disk right now.
$ spacetrace diff --path /srv
#1 2026-09-06 17:23 [weekly] → #2 2026-09-06 19:40
total 23.8 MiB → 76.3 MiB (+52.5 MiB)
CHANGE STATUS NEW PATH
+40.1 MiB grew 42.9 MiB app/logs/
+14.3 MiB grew 25.7 MiB backups/
-1.9 MiB removed 0 B uploads/Read another machine
Any read-only command takes --remote. Same subcommands, pointed elsewhere.
$ spacetrace --remote nas diff --path /var
#12 2026-09-01 03:00 [nightly] → #19 2026-09-08 03:00
total 41.2 GiB → 58.9 GiB (+17.7 GiB)
CHANGE STATUS NEW PATH
+16.9 GiB grew 21.4 GiB lib/docker/overlay2/
+0.8 GiB grew 3.1 GiB log/journal/Easy for an AI assistant to drive
Every command prints JSON, and nothing in the tool can delete a file. So you can let an assistant scan a machine, read the numbers back, and explain what filled the disk — without writing a parser and without taking a risk.
- --json on every command, so nothing has to be scraped out of human text
- Read-only: there is no delete in it for a model to reach for
- One static binary, so it drops into any container or sandbox
- --remote and plain SSH, so an assistant can look at a whole fleet
- Totals match du and df, so you can check what it concluded
The agent
spacetrace-agent is the same code as a service. It scans the roots you configure on a schedule, keeps the snapshots, and serves them over HTTP. One static binary — and it only ever reads.
- Five-field cron schedules per root, with retention by count
- Bearer token required; serve refuses to start without one
- Binds loopback by default — exposing an inventory should be a deliberate edit
- /health needs no token so a container healthcheck works, and reveals nothing else
- Unknown config keys are rejected at startup rather than silently ignored
In a container
Mount the host read-only and scan that. The image carries both amd64 and arm64.
docker run -d --name spacetrace \ -v /:/host:ro \ -v spacetrace-data:/var/lib/spacetrace \ -v /etc/spacetrace:/etc/spacetrace:ro \ -p 7878:7878 \ ghcr.io/unalcakir28/spacetrace
You can read the code
The scanner, the snapshot store, the diff and both binaries are Apache-2.0. Software you install on your own servers should be software you can inspect.