Files and folders
Every path is in your home or in your runtime folder, $XDG_RUNTIME_DIR (/run/user/<uid>). Every
name starts with the prefix, sandcastle.
| Path | What it holds | Written by | uninstall |
|---|---|---|---|
~/.config/sandcastle/ | the configuration | you | keeps it |
~/.local/share/sandcastle/secrets/ | one file per secret, readable only by you | sandcastle secret set | keeps it |
~/.local/share/sandcastle/jobs/ | the jobs’ records; it is data_dir | the core | keeps it |
~/.local/bin/sandcastle | the installed binary, which the core and the gate’s preparation run | install | keeps it |
~/.config/containers/systemd/sandcastle-link.network | the link network’s unit | install | removes it |
~/.config/containers/systemd/sandcastle-keep.container | the keep’s unit | install | removes it |
~/.config/containers/systemd/sandcastle-gate.container | the gate’s unit | install | removes it |
~/.config/systemd/user/sandcastle.service | the core’s unit | install | removes it |
~/.config/systemd/user/sandcastle-gate-repair.service, .timer | the gate’s repair, every minute | install | removes them |
~/.config/systemd/user/sandcastle.target | the target that groups the three and the gate’s repair | install | removes it |
~/.config/containers/systemd/sandcastle-*.container.d/ | your drop-ins | you | keeps them |
$XDG_RUNTIME_DIR/sandcastle-keep/keep.sock | the keep’s socket, the core’s only way to it | the keep | gone when the keep stops |
$XDG_RUNTIME_DIR/sandcastle-gate/ | the gate’s smokescreen.yaml and acl.yaml, its list of names | the gate’s preparation | gone when the gate stops |
uninstall also removes the images and the two networks, which live in Podman: see
Network names and ranges. It leaves lingering on, as other services of yours may
need it.
A different --config or --secrets folder, or $SANDCASTLE_CONFIG, moves the first two;
install writes the folders it was given into the units.
A job’s record
Each job leaves a folder under data_dir, readable only by you:
<source>/<job id>/input.json what the source sent; for ocr, the image's size and SHA-256 instead of its bytes
<source>/<job id>/output.json what was sent back, or the reply that was refused
<source>/<job id>/meta.json what happened
meta.json holds source, job, capability, status (succeeded, failed or released),
error, stderr (the start of what the box wrote there, which is hostile and is kept only here),
started_at, finished_at, and usage with the model and the tokens when the job reached one.
The core deletes the folders older than retention_days when it starts, then every hour.