Installing on macOS

On a Mac, Credenza installs with the same command as on Linux. It runs as your own user, starting when you log in, with a PostgreSQL database of its own and ffmpeg, both from Homebrew. Nothing on the machine needs Docker.

Requirements

macOS 14 (Sonoma) or later, on Apple silicon or Intel.
Homebrew. Setup uses it to install PostgreSQL 18, pgvector and ffmpeg.
The account Credenza should run as, signed in. Run the install command as that user — not with sudo: Homebrew refuses to run as root, and the server runs as whoever installs it.

Installing

Install Homebrew if the Mac does not have it yet, following the instructions at brew.sh.
Run the install command in Terminal:
Terminal window
```
curl -fsSL https://credenza.tv/install.sh | sh
```
You can read the script before running it. It downloads the release for your Mac, checks it against the release’s checksums, and starts setup.
Agree to the Homebrew step. Setup asks before it runs brew install postgresql@18 pgvector ffmpeg, then creates the database and starts the server.
Allow incoming connections. If the macOS firewall is on, macOS asks whether Credenza.Api may accept incoming network connections. Choose Allow, or other devices cannot reach it.
Open it in a browser. On the Mac, visit http://localhost:27333. The first visit creates the administrator and adds your first library — see First run.

From another device, open http://<your-mac>:27333, using the Mac’s network name or address.

Options

Pass options after sh -s --:

curl -fsSL https://credenza.tv/install.sh | sh -s -- --yes

Option	What it does
`--version <version>`	Install that version rather than the latest. Releases up to 0.2.1 have no macOS build
`--port 28000`	Listen on that port rather than 27333
`--yes`	Agree to anything setup would otherwise ask about, such as the Homebrew step
`--no-setup`	Unpack the server only; run `~/Library/Application\ Support/Credenza/app/host/setup.sh` yourself afterwards

What it sets up

What	Where
The server, its database and its data	`~/Library/Application Support/Credenza/`
The server’s and the database’s logs	`~/Library/Logs/Credenza/`
Transcoding scratch space	`~/Library/Caches/Credenza/transcode`
Two LaunchAgents, `tv.credenza.server` and `tv.credenza.postgres`	`~/Library/LaunchAgents/`
PostgreSQL 18, pgvector and ffmpeg	Homebrew’s own prefix

The database is a PostgreSQL cluster of Credenza’s own, separate from any other PostgreSQL that Homebrew runs, listening on localhost:54333 only. Its port is deliberately unusual, so a PostgreSQL you already run on 5432 is not disturbed. If 27333 or 54333 is taken, setup picks the next free port and keeps it on every upgrade.

Inside ~/Library/Application Support/Credenza/:

Folder	What is in it
`app/`	The program. Replaced on every upgrade
`postgres/`	The database: your libraries, accounts, watch history and every setting made in the browser
`data/`	Game saves, the artwork cache, the keys that keep people signed in, and exported backups
`secrets/`	The database’s password, readable by you alone

Starting and stopping

Both agents start when you log in, and macOS restarts the server if it stops. To restart it — after changing a setting that needs one, for example — run:

launchctl kickstart -k gui/$(id -u)/tv.credenza.server

To stop it until you next log in:

launchctl bootout gui/$(id -u)/tv.credenza.server

To start it again without logging out:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/tv.credenza.server.plist

Your media, and logging in automatically

Because the server runs as you, it reads whatever you can: ~/Movies, folders on external drives, and network shares you have mounted in the Finder. Add a library by its path on the Mac, such as /Users/you/Movies or /Volumes/Media/Films.

The flip side is that it runs only while you are logged in. A Mac that serves the house — a Mac mini in a cupboard, say — should log in by itself after a restart or a power cut: in System Settings → Users & Groups, set Automatically log in as to your account. macOS does not offer this while FileVault is on. A share has to be mounted again after a restart too; adding it to System Settings → General → Login Items reconnects it when you log in.

Keep the Mac awake, too, or the server sleeps with it: in System Settings → Energy (on a laptop, Battery → Options), turn on preventing automatic sleep while the display is off.

Search on Apple silicon and Intel

On Apple silicon, search uses pg_search, as on Docker and Linux. pg_search is not published for Intel Macs, so there search uses PostgreSQL’s own full-text search, as on Windows. It still matches as you type and across titles, people, studios and overviews, but it ranks results less sharply.

Settings

Almost everything is set in the browser, under Settings → Server. For the options that are set before the server starts — see Configuration — use a file:

Setup writes appsettings.Production.json in ~/Library/Application Support/Credenza/app/ on every install, so changes made there are lost on the next upgrade.
Put your own settings in appsettings.Local.json beside it instead. It is read after that file, so it wins, and an upgrade carries it over.

In the file, each part of an option’s name is a level of JSON. MediaServer__Updates__Enabled, for example, is:

{
  "MediaServer": {
    "Updates": {
      "Enabled": false
    }
  }
}

Restart the server afterwards with launchctl kickstart -k gui/$(id -u)/tv.credenza.server. To change the port, run the install command again with sh -s -- --port <n>.

Upgrading

Run the install command again:

curl -fsSL https://credenza.tv/install.sh | sh

It replaces the program, keeps the database, your data and the ports you chose, and restarts the server. The database is upgraded when the new version starts; there is no migration step to run yourself. Add sh -s -- --version <version> to move to a particular release instead of the latest.

brew upgrade is safe to run alongside: the database extensions Credenza adds itself are kept in its own folder rather than Homebrew’s, so upgrading Homebrew’s packages leaves them in place.

Uninstalling

~/Library/Application\ Support/Credenza/app/host/uninstall.sh

That stops and removes both agents, the program and the transcoding scratch space, and keeps the database, your data — game saves, artwork and backups — and the logs, so a reinstall finds your library again. To remove those too:

~/Library/Application\ Support/Credenza/app/host/uninstall.sh --purge

Neither removes PostgreSQL, pgvector or ffmpeg from Homebrew, since other things may use them; brew uninstall postgresql@18 pgvector ffmpeg does, if nothing else does.

When something goes wrong

Every log is in ~/Library/Logs/Credenza/: the server’s own log files, which are also readable at Settings → Server → Logs, what the server printed while starting, and the database’s postgres.log.

To check whether the server is answering at all, on the Mac:

curl -s http://127.0.0.1:27333/api/status

Nothing answers: check you are logged in, then restart it with launchctl kickstart -k gui/$(id -u)/tv.credenza.server and read the newest files in ~/Library/Logs/Credenza/. Running the install command again repeats every setup step and is safe to do as often as you like.
It answers on the Mac but not from other devices: the macOS firewall is blocking it. In System Settings → Network → Firewall → Options, set Credenza.Api to allow incoming connections.
A library on an external drive or a share finds nothing: check the drive or share is mounted in the Finder. If macOS asked whether Credenza.Api may access files on a removable or network volume, it needs Allow. If you missed the question, add ~/Library/Application Support/Credenza/app/Credenza.Api under System Settings → Privacy & Security → Full Disk Access. An upgrade replaces that file, so macOS may ask again.