Configuration & API

The registry lists catalogs and image folders. The server TOML controls runtime settings. The REST API exposes the same operations as the UI.

CLI / NAS
This page is for server and API setups

Most desktop users can manage catalogs in Settings and stop there.

CLI reference →

Catalogs: the registry

The server manages any number of image catalogs. Each uses the inherited Target Scheduler database mapping. The list lives in a JSON registry at the platform config location — not in the TOML:

PlatformRegistry path
Windows%APPDATA%\psf-guard\config.json
macOS~/Library/Application Support/psf-guard/config.json
Linux~/.config/psf-guard/config.json

psf-guard server <db> <dirs...> registers that database on first run and reuses it afterwards; you can also manage the list from the desktop app's Settings panel or the /api/databases endpoints. For a one-off session that shouldn't touch your real config, pass --registry /tmp/scratch.json.

The default N.I.N.A. scheduler database on Windows lives at %LOCALAPPDATA%\NINA\SchedulerPlugin\schedulerdb.sqlite.

Seiza catalogs and plate solving

PSF Guard uses Seiza's standard catalog discovery. Data installed by seiza setup is found automatically; a custom bundle directory can be selected with SEIZA_CATALOG_DIR or the registry's top-level astrometry.data_dir field:

"astrometry": {
  "data_dir": "/path/to/seiza-data",
  "satellite_elements": "historical-or-active.tle"
}

Restart PSF Guard after changing this process-global setting. See Sky Context & Plate Solving for the download commands, required files, Docker mount, capability validation, UI workflow, and solution cache behavior.

Server knobs: the TOML

cp psf-guard.toml.example psf-guard.toml
psf-guard server --config psf-guard.toml
[server]
port = 3000
host = "0.0.0.0"
# Optional: fraction of CPU cores for parallel work (both default sensibly).
# Interactive jobs (occlusion scans, on-demand previews) get scan_worker_ratio;
# background pre-generation gets background_worker_ratio and pauses entirely
# while an interactive job runs.
#scan_worker_ratio = 0.5
#background_worker_ratio = 0.25

[cache]
directory = "./cache"
file_ttl = "5m"        # 30s, 5m, 1h, 2h30m, 1d ...
directory_ttl = "5m"

[pregeneration]        # optional background preview warming
enabled = true
screen = true          # 1200px previews
large = false          # 2000px previews

Command-line arguments override the config file. A legacy [database]/[images] section is still parsed but ignored in server mode — databases come from the registry.

REST API

Per-database endpoints are nested under /api/db/{db_id}/; GET /api/databases lists the configured databases and their ids.

# List images with filters
curl "localhost:3000/api/db/my-db/images?project_id=2&status=pending"

# Update a grade
curl -X PUT localhost:3000/api/db/my-db/images/123/grade \
  -H "Content-Type: application/json" \
  -d '{"status": "accepted"}'

# Start and inspect a target-aware quality scan
curl -X POST localhost:3000/api/db/my-db/analysis/quality-scan \
  -H "Content-Type: application/json" \
  -d '{"target_id": 42}'
curl localhost:3000/api/db/my-db/analysis/quality-scan

# Fetch processed images
curl "localhost:3000/api/db/my-db/images/123/preview?size=large" -o preview.png
curl "localhost:3000/api/db/my-db/images/123/annotated" -o stars.png

# Catalog capability diagnostics and on-demand plate solving
curl "localhost:3000/api/astrometry/capabilities"
curl "localhost:3000/api/db/my-db/images/123/astrometry"
curl -X POST "localhost:3000/api/db/my-db/images/123/astrometry"

# Cached or on-demand satellite prediction
curl "localhost:3000/api/db/my-db/images/123/satellites"
curl -X POST "localhost:3000/api/db/my-db/images/123/satellites"

Export has a read-only streaming ZIP route and a management-gated server-local folder route. See Export for Stacking for request options and examples.

Preview and annotated images generate asynchronously: a cache miss returns HTTP 202 ({"state": "generating"}) and a batch generation-status endpoint reports readiness — the UI uses this to show its "Generating…" badges without long-lived requests.

The quality scan first computes spatial/photometric metrics, then fresh pixel-derived plate solutions. Results persist in the per-database cache and feed the sequence-analysis endpoint. See Astrometry Quality for target provenance, failure semantics, and regrade safety.

Database management endpoints (POST/PUT/DELETE /api/databases) are disabled unless the server runs with --allow-database-management, since they let any reachable client edit your configured database list. The desktop app always enables them for its own local server.

Known limitations