A self-hosted web app that reads your music library, lists every artist in it, and keeps track of what they release next. Follow an artist with one click; set them to Notify and you're told when something new is announced. It also finds new music you don't have, shows what's missing from your collection, and can fetch it for you from Soulseek.
SQLite for storage, a React frontend, and plugins for everything outside the app: libraries, discovery sources, download clients, metadata sources and notification services. Dark (AMOLED pure black) and light themes, and installable as a PWA.
See screenshots of every page →
- Several libraries at once. Scan a folder of music files (mp3, flac, m4a, ogg, opus, wav and more), or read a Navidrome / Subsonic or Plex server. Each source is scanned on its own schedule, and what they own is combined.
- Quick scan for folders: after the first full scan, only files added or changed since the last one are read.
- Owned albums, with quality and track count. Discographies show what you have and in which format ("FLAC", "MP3 320"). Albums you own with fewer tracks than a complete copy are flagged as incomplete.
- Play what you own. Album pages stream the full track from whichever library has it (in the order you choose), and fall back to a 30-second preview from iTunes, Deezer or Last.fm for anything you don't.
- Tidy artists. Merge duplicates ("Beatles" and "The Beatles"); the app suggests likely duplicates itself. Match an artist to MusicBrainz by pasting a link. Ignore artists you don't care about; they're moved to an Ignored page and nothing is lost.
- Two levels per artist. Follow tracks their releases on the Following and Upcoming pages. Notify also sends a notification for each new release, either as soon as it's found or a set time before the release date.
- Choose release types per artist: any mix of Albums, EPs and Singles, with a default for new follows.
- Full discography on demand. An artist page lists every album, EP and single from MusicBrainz, marks the ones you own, and tags EPs and singles with how many of their songs you don't have yet. Mark a release Not interested and it stops counting as missing.
- Monitor artists who aren't in your library by pasting a MusicBrainz link or ID.
- An agenda (this week, next week, by date) and a month calendar of releases from the artists you follow. Filter by type; live albums and compilations are hidden unless you switch on Live & comps. Past weeks shows what came out recently, with a check on what you already own.
- Calendar feed: subscribe to a private
.icslink in any calendar app. - Get Hyped playlist: builds a playlist on Navidrome of songs you already own by the artists with a release due, by hand or weekly.
New music you don't have yet, in the same agenda and calendar views. Each source can be switched on or off:
- Last.fm "coming soon" recommendations (needs your Last.fm session cookie), with the reason for each ("you've scrobbled…", "similar to…").
- Metacritic release calendar.
- Album of the Year upcoming releases (behind Cloudflare: paste a clearance cookie, or run FlareSolverr to solve the challenge automatically).
- Indie Is Not A Genre new and upcoming releases.
- AllMusic featured new releases each week, with ratings and Editors' Choices.
- ListenBrainz fresh releases (everything new in MusicBrainz), kept to artists similar to yours, tags you choose, or the picks for your ListenBrainz account.
- New from your library: new releases by artists you own but don't follow, from the same ListenBrainz list.
- KEXP radio plays: new records the station is airing and how often.
- Hype Machine: what music blogs are posting now.
- Reviews and announcements from Pitchfork, Stereogum, Consequence, Paste, NME, DIY, The Quietus and BrooklynVegan (their RSS feeds), and AnyDecentMusic? critic averages.
The sources from AllMusic down are off until you switch them on under Settings > Discovery.
- Similar artists, gathered from Last.fm, and Your Last.fm: the artists you play most that aren't in your library.
Each release shows the artist's genres as tags, and has a play button: it plays the release's tracks (your own copy if a library has it, else a preview), or the artist's top tracks when nothing on the record is out yet, and the player says so. Switch on Continue to next artist and it carries on down the list; the row playing is highlighted, and releases you've already heard are skipped. The audio for every release from this week to a month out, on Discover and Upcoming, is looked up in the background ahead of time (Settings > Discovery > Pre-load audio), so play starts at once. Every preview it finds, and every one you play, is saved to disk as `data/previews//
- <Title>.mp3` (all songs of each release or a set number, picked by a
slider; 5 GB by default, least recently played go first), so it keeps playing after the catalogue's link has lapsed and the folder can be browsed in any music player. For a Hype Machine row that's the whole song the blog posted. While the pre-load runs, pages play only audio that's already been found and look nothing up themselves.
Every request to an outside service -- from the background jobs, the plugins and the pages alike -- shares one request budget per service, set from that service's published limit (iTunes about 20 searches a minute, Deezer 50 per 5 seconds, MusicBrainz one a second, Last.fm five a second, gentler for scraped sites). A service that answers "slow down" (429, 503, Retry-After, rate-limit headers, or its own quota error) is left alone for as long as it asks, and that answer is never stored as "not found". Your own servers (music libraries, slskd, FlareSolverr) aren't limited.
- For you: sort the feed by how well each release fits you (similar to your artists, your Last.fm plays, the genres you collect, critic score, how many sources list it), with the reasons on each row. Or sort by critic score (Metascores from Metacritic's new releases).
- Genre filter: show only some genres, or hide some; click any genre tag to filter by it. A button looks up tags for the artists that have none.
- Heard: releases you've played are marked and dimmed, can be hidden, and the continue walk skips them.
- New since your last visit: marked on the rows, and counted on the Discover tab in the navigation.
- Wanted: keep an album you can't get yet (not out, or nowhere to download it) on a list, from Discover, an album page or a discography. The Wanted tab (on Discover and Missing) lists them; each is announced on its release day, can be grabbed automatically then, and drops off once a library owns it.
- Weekly digest: the week's top picks by the For you ranking, sent to your notifiers on a day and time you choose.
The player plays the whole list the same way on Upcoming and on Similar
Artists (their top tracks). It has a queue view, a next artist button,
thumbs up (save the release or follow the artist) and thumbs down
(hide the release from Discover), keyboard shortcuts (space, n, p,
shift+N), lock-screen and headphone controls on phones, and a sampler setting
that plays only a release's most played tracks.
- Missing: every release by your artists that no library owns, filtered by type, with reissues, live albums and compilations hidden by default.
- Incomplete: albums you own with fewer tracks than the shortest official edition on MusicBrainz, with a button to fetch just the missing tracks.
- Quality profile: which formats are acceptable, best first. Soulseek searches only for those.
- One-click grab from the Missing page or an album page, through slskd (Soulseek).
- Automatic grabbing (off by default) of new releases from the artists you choose, within a set age and batch size.
- Duplicate protection: nothing is sent if the library already owns it or the download client already has it.
- Soulseek downloads followed to the end. Every file of an slskd download is tracked. A failed file is retried, then fetched from another peer (same format only), and a download that still ends short searches again later. The Downloads tab shows each file and lets you retry, try another peer, or cancel.
- Choose where information comes from. For each field (artist photos, bios, genre tags, similar artists, album covers, write-ups, previews) you order the sources: Last.fm, Deezer, iTunes, the Cover Art Archive, and your own release covers.
- Artwork kept on disk, so pages load instantly and work offline. A review tool helps pick photos for artists that have none.
- Find missing metadata across every followed artist and fill it in from the sources.
- Notifications through ntfy, Gotify, Discord or a custom webhook, each subscribed to the events it wants: new release found, release day, release sent to the download client, Soulseek download finished or incomplete, scan finished, the weekly Discover picks, and a saved release coming out.
- Search links: add your own search sites (a tracker, a record shop, a
wiki) with a URL like
https://example.com/torrents.php?searchstr={query}; each shows as an icon, the site's own favicon or one you choose, beside every release's Last.fm / MusicBrainz / YouTube Music links. - Backup and restore as a ZIP file: settings, artist information, your lists (Wanted, Not interested, ignored releases, album matches, heard) and artwork, each optional. Older JSON backups still import.
- Maintenance: control how long scraped data is kept, delete what belongs to artists you've unfollowed, and compact the database.
- Configurable navigation: drag the tabs into the order you want; the top one is your home page.
- Works on a phone: a bottom tab bar and the player stay in reach, and the app can be installed to the home screen.
- Sign-in with a password or your own single sign-on provider (OpenID Connect), API tokens for scripts, and a guided first-run setup: see Security.
- Scheduled tasks listed in Settings with when each last ran and runs next.
- A JSON API for everything the UI does.
Only artists you follow are checked for new releases. At MusicBrainz's limit of about one request a second, sweeping a library of thousands of artists isn't practical, so tracking is scoped to the ones you chose.
A GitHub Actions workflow builds a multi-arch image (linux/amd64 +
linux/arm64) and publishes it to the GitHub Container Registry on every
push to the default branch and every vX.Y.Z tag. Available tags:
ghcr.io/jasii/simple-music-tracker:latest- newest default-branch buildghcr.io/jasii/simple-music-tracker:v1.2.3- a specific release tag
Pull and run it directly:
docker run -d -p 8080:8080 \
-e PUID=$(id -u) -e PGID=$(id -g) \
-v "$(pwd)/data:/data" \
-v "/path/to/your/music:/music:ro" \
--name simple-music-tracker \
ghcr.io/jasii/simple-music-tracker:latestPUID and PGID (default 1000) set the user and group the app runs as, so
the files it writes under /data belong to you on the host; GUID works as
another name for PGID. On start the container hands anything under /data
owned by someone else (an older image ran as root) over to that user. Set
PUID=0 to run as root as before.
The music folder is optional: skip it if your library is on Navidrome or Plex, or if you'd rather add artists by hand.
Or use the provided docker-compose.example.yml.
It has the music volume and an optional FlareSolverr service commented out;
uncomment what you need:
docker compose -f docker-compose.example.yml up -d
# update later:
docker compose -f docker-compose.example.yml pull
docker compose -f docker-compose.example.yml up -dThen open http://localhost:8080.
Everything the app keeps (the database, cached images and all other caches)
lives under /data. Back that folder up to back up the whole app.
The workflow at .github/workflows/docker-publish.yml runs automatically once
the code is on your default branch. To publish:
- Merge to
main(or push a tag likev1.0.0), or trigger it manually from the repo's Actions tab (it supportsworkflow_dispatchon any branch). - The first successful run creates the package under your repo's Packages. If you want anyone to pull without authenticating, open the package settings and set its visibility to Public.
- Pulling a private package requires a GitHub token with
read:packages:echo $TOKEN | docker login ghcr.io -u <username> --password-stdin.
No secrets are needed for publishing - the workflow uses the built-in
GITHUB_TOKEN with packages: write permission.
The Dockerfile builds the frontend in a Node stage and copies it into the Python image, so there's nothing to build beforehand.
-
Edit
docker-compose.ymland point the music volume at your library:volumes: - ./data:/data - /path/to/your/music:/music:ro
-
Build and start:
docker compose up -d --build
-
Open http://localhost:8080.
Or with plain Docker:
docker build -t simple-music-tracker .
docker run -d -p 8080:8080 \
-e PUID=$(id -u) -e PGID=$(id -g) \
-v "$(pwd)/data:/data" \
-v "/path/to/your/music:/music:ro" \
--name simple-music-tracker simple-music-trackerThe first time you open the app it runs a short setup:
-
Setup code. A new install only answers its setup page, and to prove the install is yours it asks for a code printed when the container starts:
docker logs simple-music-tracker 2>&1 | grep -A3 "setup code"
The code is also in
setup-code.txtin your data folder (only the app's user can read it). SetSMT_SETUP_CODEin the environment to choose your own instead. It stops working once setup has made the account. -
Sign-in. Pick a username and password (recommended), or No login if a reverse proxy in front already signs people in, or the app never leaves the machine. Single sign-on can be added afterwards in Settings > Security.
-
Library. Choose where your music lives (a folder mounted at
/music, Navidrome / Subsonic, or Plex), fill in its details, Test it and start a scan. The scan runs in the background while you carry on. Moving from another install? Restore a backup here instead. -
Last.fm. A free API key (https://www.last.fm/api/account/create) gives artists their bios, pictures, tags and similar artists. Optional, but much of Discover needs it.
-
Extras. Optional: a download client (slskd), notifications (ntfy, Gotify, Discord) and FlareSolverr.
Every step after the account can be skipped and comes back where you left it if you close the tab. Everything is in Settings later, and Settings > System > Run setup again repeats steps 3 to 5.
Then follow artists on the Artists page (tick Follow, or Notify to be told about new releases). Following fetches their releases straight away; after that a background job checks again on the interval you set. Settings > Sources > Keys & accounts also takes a MusicBrainz contact (email or URL), which MusicBrainz asks for in the User-Agent.
Upgrading an install from before accounts existed: it keeps working without a login and shows a banner until you set one up in Settings > Security.
To monitor an artist that isn't in your library, paste a MusicBrainz artist
link (e.g. https://musicbrainz.org/artist/<mbid>) or a raw artist ID into the
"Monitor an artist by MusicBrainz link" box on the Artists page. The artist is
looked up, added and followed immediately.
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
(cd frontend && npm ci && npm run build) # builds into app/static/spa
SMT_DB_PATH=data/tracker.db python -m app.main # serves the app on :8080
# or production:
gunicorn --workers 1 --threads 32 --timeout 120 --bind 0.0.0.0:8080 app.main:appUse a single worker (with threads) so the in-process scheduler and the scan, refresh and download state stay consistent.
For frontend development, run the backend as above and start Vite alongside it. It serves the UI with hot reload on http://localhost:5173 and proxies API calls to the backend on port 8080:
cd frontend && npm run devEverything the app talks to is a plugin under app/plugins/, switched on and
configured under Settings. Adding a service means adding one file.
| Kind | Bundled |
|---|---|
| Library | Music folder, Navidrome / Subsonic, Plex |
| Discovery | Last.fm, Metacritic, Album of the Year, Indie Is Not A Genre, AllMusic, ListenBrainz, New from your library, KEXP, Hype Machine, AnyDecentMusic?, Pitchfork, Stereogum, Consequence, Paste, NME, DIY, The Quietus, BrooklynVegan |
| Metadata | Last.fm, Deezer, iTunes, Cover Art Archive, your own release covers |
| Download clients | slskd (Soulseek) |
| Notifications | ntfy, Gotify, Discord |
| Challenge solvers | FlareSolverr |
| Search links | Your own sites (Settings > Downloads & quality) |
A notification service (ntfy, Gotify, Discord) picks the events it wants from a checkbox list, so one can carry release announcements while another only reports downloads.
For Notify artists, the custom webhook fires once per newly discovered release. Configure its URL, method, headers and a JSON body template under Settings > Notifications. The body template supports these placeholders:
{artist} {title} {release_date} {type} {image_url}
Default payload:
{
"event": "new_release",
"artist": "{artist}",
"title": "{title}",
"release_date": "{release_date}",
"type": "{type}",
"image": "{image_url}"
}Use Send test webhook in Settings to check your endpoint.
Everything the UI does goes through the JSON API. The most useful endpoints:
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/stats |
Library counts and upcoming totals. |
| GET | /api/artists |
List artists. Params: q, subscription (none|subscribed|notify|following), ignored (0 hide ignored - default, 1 only ignored, all), sort (name|tracks|recent), limit, offset. |
| GET | /api/artists/<id> |
Artist detail with tracked releases. |
| GET | /api/artists/<id>/discography |
All albums/EPs/singles from MusicBrainz, with what you own. |
| POST | /api/artists/<id>/subscription |
Body {"state": "none|subscribed|notify"} (none / Follow / Notify). |
| POST | /api/artists/subscriptions |
Bulk: {"ids": [...], "state": "..."}. |
| POST | /api/artists/add |
Monitor an artist from a MusicBrainz link/ID. Body {"link": "https://musicbrainz.org/artist/<mbid>", "state": "subscribed|notify", "types": ["album","ep","single"]}. |
| POST | /api/artists/track-by-name |
Monitor an artist by name. Body {"name": "Artist", "state": "subscribed|notify"}. |
| POST | /api/artists/<id>/monitor-types |
Set watched release types. Body {"types": ["album","ep","single"]}. |
| POST | /api/artists/<id>/ignore |
Hide/unhide an artist. Body {"ignored": true|false}. |
| POST | /api/artists/<id>/mbid |
Match an artist to a MusicBrainz URL/ID. Body {"link": "..."}. |
| POST | /api/artists/<id>/merge |
Merge other artists into this one. Body {"source_ids": [...], "name": "<optional>"}. |
| POST | /api/artists/<id>/refresh |
Re-fetch one artist's info and releases now. |
| GET | /api/subscriptions |
All followed artists. |
| GET | /api/upcoming |
Upcoming releases. Param window: day, week, next-week, month, all. |
| GET | /api/upcoming/releases |
Releases in a date range. Params from, to (YYYY-MM-DD). |
| GET | /api/discover/releases |
Releases from every enabled discovery source. ?refresh=1 re-fetches. |
| GET | /api/album/playable |
Where each track of a release plays from. Params artist, title, mbid. |
| GET | /api/artist-top-tracks |
An artist's top tracks with audio, by name. Params artist, limit (1-10). |
| GET | /api/prewarm/status · POST /api/prewarm |
Pre-load of this month's release audio: progress, or start it ({"stop": true} stops). |
| GET | /api/search-links |
Your search sites, with their icons. |
| GET/POST/DELETE | /api/wishlist |
Releases saved for later. POST {"artist", "album", "mbid"?, "release_date"?, "image"?}, DELETE {"artist", "album"}. |
| POST/DELETE | /api/heard |
Mark a release as listened to, or not. Body {"artist", "album"}. |
| GET | /api/discover/unseen |
How many Discover releases are new since the last visit. |
| GET | /api/discover/digest · POST /api/discover/digest/send |
Preview the weekly digest, or send it now. |
| GET | /api/album |
Tracklist, cover and what you own of one release. Params artist, title, mbid. |
| GET | /api/library/missing |
Releases no library owns. Params q, types, sort, limit, offset. |
| GET | /api/library/incomplete |
Albums owned with fewer tracks than a complete copy. |
| POST | /api/library/grab |
Grab one release through the download client. Body {"artist", "title"}. |
| POST | /api/library/grab-missing |
Fetch the missing tracks of an owned album. Body {"artist", "title", "tracks"?}. |
| GET | /api/downloads |
Soulseek downloads, file by file. ?active=1 for running ones only. |
| POST | /api/downloads/<id>/retry · /another-peer · /cancel |
Act on one download. |
| GET | /api/autograb/status |
What the automatic pass would grab next. |
| GET | /api/plugins |
Every plugin, whether it's enabled and configured, and its settings. |
| POST | /api/plugins/library/<key>/scan |
Scan one library source. |
| POST | /api/scan |
Scan the music folder. Body {"quick": true} for only added/changed files. |
| POST | /api/refresh |
Refresh all followed artists. |
| GET/POST | /api/settings |
Read or update settings. |
| GET | /api/backup |
Download a ZIP backup. ?sections=settings,artists,artwork (default all). |
| POST | /api/import |
Restore from a backup (multipart file). ZIP or legacy JSON. |
| GET | /calendar/<token>.ics |
The private calendar feed (the link is under Settings > Maintenance). |
| POST | /api/webhook/test |
Fire a sample webhook. |
| GET | /api/health |
Health check. |
Example - albums dropping this week:
curl http://localhost:8080/api/upcoming?window=weekFor each followed artist the app:
- Resolves the artist to a MusicBrainz ID (using an embedded
musicbrainz_artistidtag if present, otherwise a name search). - Lists the artist's release groups of the types you watch (Albums / EPs / Singles) from MusicBrainz.
- Keeps the ones whose first release date is in the future or within the last 30 days, and stores them.
- Links cover art from the Cover Art Archive.
- MusicBrainz: all refresh work goes through a single background worker,
so however many artists you follow at once, requests are made one at a time.
They're paced by a configurable minimum gap (default and floor
1000ms, one request a second), carry a descriptive User-Agent, and are retried with exponential backoff (300ms · 2^n, honouringRetry-After) on connection errors and429/500/502/503/504. A404counts as "not found" and isn't retried. - Last.fm: a 6s timeout with up to 2 retries and a small backoff.
- Similar artists: the library scan and the genre lookup take one artist at a time, a second apart.
- Soulseek: one slskd search at a time.
Scraped answers are stored in the database (forever by default, configurable under Settings > Maintenance), so browsing a page a second time costs no requests at all.
- Backend: Python 3.11, Flask, SQLite (stdlib
sqlite3), gunicorn.requestsfor API calls,mutagenfor reading tags,beautifulsoup4andcurl_cffifor scraping discovery pages, and optionallyyt-dlpto play the audio of video-only previews. - Frontend: React 18 + TypeScript, built with Vite. shadcn/ui components on Tailwind CSS v4, TanStack Query for data, and React Router. PWA via manifest + service worker.
app/
main.py Flask app: hooks, blueprint registration, the built frontend
routes/ JSON API, one blueprint per area (artists, discover, ...)
discover_feed.py The merged Discover feed and its background refreshes
upcoming.py Followed artists' releases by date
db.py SQLite schema, settings, migrations, helpers
scheduler.py Background jobs (refreshes, scans, grabbing, downloads)
tracker.py Per-artist refresh, through a single worker
musicbrainz.py Discographies and upcoming releases (rate-limited)
scanner.py Music folder scanning (mutagen)
gaps.py Missing / incomplete lists
grabber.py Sends a release to the download client
downloads.py Follows Soulseek downloads file by file
quality.py Quality profile
metadata.py Asks metadata sources in the order you set
calendar_feed.py The .ics release calendar
... Playback, artwork cache, previews, playlists, maintenance
plugins/ library, discovery, metadata, downloader,
notifier and solver plugins
static/ Icons, manifest, service worker; built frontend in static/spa
frontend/
src/pages/ One file per page (Discover, Artists, Missing, Settings, ...)
src/components/ Shared components; ui/ holds the shadcn components
screenshots/ The images in screenshots.md
Dockerfile, docker-compose.yml, docker-compose.example.yml, requirements.txt
A new install asks for a setup code (printed in docker logs, see
First-time setup) before it will make an account, and
answers nothing else until then.
Settings > Security sets how people sign in:
| Mode | Who gets in |
|---|---|
| Password | The account made in setup. Passwords are hashed with scrypt. |
| Password or single sign-on | Either. |
| Single sign-on only | Your OpenID Connect provider. Can only be switched on from a session that signed in with SSO, so you know it works first. |
| No login | Anyone who can reach the app. For a reverse proxy that does its own sign-in, or an app that never leaves the machine. |
- Sessions last 30 days since you last used them (12 hours without "Keep me signed in"), and 90 days at most. The cookie holds random bytes; the database keeps only their hash. Settings > Security lists signed-in devices and signs any of them out. Changing the password signs out every other device.
- Guessing is slowed down: after 5 wrong tries from one address or for one username, each further try waits twice as long as the last, up to 15 minutes.
- API tokens for scripts are made (and shown once) in Settings >
Security, and sent as
Authorization: Bearer <token>.SMT_AUTH_TOKENin the environment also works as one. A token can use the whole API but can't manage sign-in. - Still open without signing in:
/api/health(health checks), the app's static files and page shell (they hold no data), and the calendar feed (/calendar/<token>.ics, which carries its own token). - Backups never carry accounts, sessions, tokens or sign-in settings, and restoring one doesn't change them.
Locked out? Set SMT_AUTH_MODE=local (or none) on the container and
restart; it overrides the mode chosen in Settings. To set a new password:
docker exec -it -u app simple-music-tracker python -m app.auth reset-password <username>
docker exec -it -u app simple-music-tracker python -m app.auth list-usersUpgrading from a version without accounts: an install that was open
stays open, with a banner, until you make an account in Settings >
Security. One that used the old auth_token setting or SMT_AUTH_TOKEN
keeps asking for that token at the sign-in page until you make an account;
the stored token becomes an API token named "Access token (migrated)".
Works with Authentik, Authelia, Pocket ID, Keycloak, Zitadel and other OpenID Connect providers.
- In your provider, make a confidential client using the authorization code
flow. Its redirect URI is shown in Settings > Security > Single sign-on
(
https://<your address>/auth/oidc/callback). - In that card, enter the provider's issuer URL, the client ID and client secret, press Test, then Connect my account and sign in at the provider.
- Choose Password or single sign-on (or Single sign-on only after signing in with it once).
Examples of the issuer URL:
- Authentik:
https://auth.example.com/application/o/<application slug>/ - Pocket ID:
https://id.example.com - Authelia:
https://auth.example.com - Keycloak:
https://kc.example.com/realms/<realm>
Only the account connected to an SSO identity can sign in with it: other people with accounts at the same provider are refused. The app matches the provider's subject ID, never the email address. A provider on the internet must use https; plain http is accepted for private addresses.
Behind a proxy (Caddy, Traefik, nginx, Pangolin...), set
SMT_TRUSTED_PROXIES to the number of proxies in front (usually 1). The
app then believes the X-Forwarded-For/-Proto/-Host headers they add, which
gives it the visitor's real address (for the guessing limit and the device
list), HTTPS (for Secure cookies) and the public host. Without it those
headers are ignored, because anyone can send them. If the SSO redirect URI
comes out wrong, set the app's address in Settings > Security.
Do not put the app on the internet with No login unless the proxy signs people in.
- Cross-site requests. Anything that changes data (POST, PUT, PATCH,
DELETE) is refused with 403 when the browser says it came from another
site (
Origin/Refererhost differs from the host it was sent to). - Headers. Pages can't be framed by other sites (
X-Frame-Options: DENY), content types aren't sniffed, and the referrer stays on this site. - Secrets in Settings. Tokens, passwords, API keys and webhook headers are never sent back to the browser: Settings shows them as "Saved". Typing a new value replaces one; Clear removes it.
- Image proxy.
/art?u=only fetches images from public addresses (private, loopback and link-local addresses are refused, redirects are checked hop by hop), and it never redirects the browser. - Webhooks may go to private addresses (Home Assistant, n8n) unless the
allow_private_webhookssetting isfalse. Redirects aren't followed. - Uploads (backup imports) are capped at 512 MB; set
SMT_MAX_UPLOAD_MBto change it.
Backend tests and lint (a temp database per test; no background jobs start):
uv venv .venv && uv pip install -p .venv/bin/python -r requirements-dev.txt
.venv/bin/pytest -q
.venv/bin/ruff check app testsFrontend (from frontend/):
npm ci
npx tsc -b # typecheck
npm run lint # ESLint (hooks rules, unused code)
npm test # VitestCI runs all of these on Forgejo (.forgejo/workflows/ci.yaml).