Getting Started

PSF Guard points at your N.I.N.A. Target Scheduler database and image folders and gives you a visual grader, automatic quality screening, and safe file management — with every grade written back to the scheduler.

Back up your Target Scheduler database before first use. PSF Guard writes grades into it, and its sync commands can merge entire databases between machines. It's careful (dry-run flags everywhere), but it's also young software.

What you need

N.I.N.A. with the Target Scheduler plugin — images are located through the scheduler database, not by walking N.I.N.A.'s standard file layout. On Windows the database lives at %LOCALAPPDATA%\NINA\SchedulerPlugin\schedulerdb.sqlite.
Monochrome FITS files — color/OSC frames are not debayered yet.

Desktop app (Windows / macOS / Linux)

Grab the installer for your platform from the latest release:

Platform	Asset
Windows x64	`PSF.Guard_<version>_x64_en-US.msi` or the NSIS `-setup.exe`
macOS (Apple Silicon)	`PSF.Guard_<version>_aarch64.dmg`
Linux x64	`PSF.Guard_<version>_amd64.deb` or `.AppImage`

Install, launch, and point the settings panel at your scheduler database and image directories. The Windows NSIS installer also installs a console psf-guard-cli.exe and adds it to your user PATH, so the full CLI works from any terminal.

Docker (Linux servers / NAS)

docker run -d -p 3000:3000 \
  -v /path/to/schedulerdb.sqlite:/data/database.sqlite \
  -v /path/to/images:/images:ro \
  ghcr.io/theatrus/psf-guard:latest

Then open http://localhost:3000/. The database mount must be writable — grading writes back to it. To tune the port, cache, or preview pre-generation, mount a TOML config at /data/config.toml and append server --config /data/config.toml /data/database.sqlite /images (see Configuration).

Standalone CLI binaries

Version-independent links, always pointing at the latest release:

Platform	Download	Notes
Linux x64	`psf-guard-linux-x64`	Needs system OpenCV — Docker is easier
macOS	`psf-guard-macos-x64`	Needs Homebrew OpenCV
Windows x64	`psf-guard-windows-x64.exe`	Static binary, no dependencies

# Linux / macOS
chmod +x psf-guard-*
./psf-guard-linux-x64 server schedulerdb.sqlite /path/to/images/

:: Windows — back up the DB first, then serve it
copy "%LOCALAPPDATA%\NINA\SchedulerPlugin\schedulerdb.sqlite" schedulerdb-backup.sqlite
psf-guard-windows-x64.exe server "%LOCALAPPDATA%\NINA\SchedulerPlugin\schedulerdb.sqlite" C:\path\to\images

Then open http://localhost:3000/.

Fedora RPM

Releases attach prebuilt RPMs for Fedora 43 and 44:

sudo dnf install ./psf-guard-*.fc44.x86_64.rpm

The package installs the CLI/server plus a psf-guard.service systemd unit for running the PSF Guard server as a daemon. To build your own, see packaging/rpm/README.md.

Build from source

git clone https://github.com/theatrus/psf-guard.git
cd psf-guard
cargo build --release
./target/release/psf-guard server schedulerdb.sqlite /path/to/images/

You'll need Rust, Node.js/npm (the React frontend is embedded at build time), and OpenCV with clang. OpenCV is the painful one — the CI workflows are the authoritative package lists per platform (vcpkg on Windows, Homebrew on macOS, libopencv-dev on Debian/Ubuntu).

Your first session

Serve your database: psf-guard server schedulerdb.sqlite /path/to/images/ — this registers it in PSF Guard's database registry, so later runs pick it up automatically.
Open http://localhost:3000/ and browse the overview.
Open a project's grid and start grading — see The Grader UI for the keyboard workflow.
Try an automatic pass: open a target's Sequence view and press Scan Occlusion, or run psf-guard screen-fits on a night of lights — see Quality Screening.
When you're done, archive the rejects out of your stacking tree — see Rejects & Sync.