2. Installation

Audiogravi^ty installs in a single command. The installer detects your architecture, generates security keys, configures the systemd service and starts everything — usually under five minutes from curl to the interface. No compilation, no dependency hell, no manual configuration.

The installer sets up Audiogravi^ty itself, and MPD with it — the player everything goes through. The other engines it conducts (AirPlay, UPnP, Roon Bridge, HQPlayer NAA, HQPlayer Embedded) are yours to choose afterwards, in a few clicks from the interface — that's step 3 of 3. First run.

Before you start

A Linux host next to your hi-fi running Debian 13 (Trixie) or later — DietPi and Raspberry Pi OS included, in their Trixie release — on x86-64 or aarch64 (Raspberry Pi). On another system, the core installer stops and says why. See 1. Introduction → What you need.
The host reachable on your local network.

Recommended — all-in-one (one box)

Installs the core (the engine) and the ui (the interface) on the same box. This is the standard setup and the one one-click self-update fully supports.

curl -fsSL https://audiogravity.app/install.sh | sudo bash

On a new install, it asks two questions about the interface: press Enter at both. The interface is then served over HTTPS on port 443 — the setup this manual describes, and the one notifications and passkeys need.

Then open, in any browser on your network, the address the installer prints at the end — the box by its name (see First contact):

https://<name>.local

On an iPhone or iPad, trust the box's certificate first (3. First run → 7): until then, Safari does not open that address.

Advanced — core and ui separately

You can install the two parts independently — for example to run the interface on a different machine. Run each installer on its target host:

curl -fsSL https://audiogravity.app/install-core.sh | sudo bash
curl -fsSL https://audiogravity.app/install-ui.sh   | sudo bash

Split installs and updates. One-click self-update updates a co-located core + ui together. If core and ui live on different hosts, update each side separately (see 8. Updating).

Optional flags (core installer)

Flag	What it does
`--vapid-email you@example.com`	The contact address push notifications are signed with, for the services that deliver them. Omitted → Audiogravi^ty's own, `push@audiogravity.app`.
`--public-url https://your.domain`	The address passkeys (Face ID / Touch ID) work from — a name, never a bare IP. Needed only for a domain of your own, a reverse proxy or an interface on another machine: when the interface runs on the box in HTTPS, its installer sets the box's name — unless another device of the network already answers to it.

curl -fsSL https://audiogravity.app/install-core.sh | sudo bash -s -- \
    --vapid-email you@example.com \
    --public-url https://audiogravity.example.com

Use the exact origin your browser shows (scheme + host + port). Example: --public-url https://ag.example.com:8443 → WEBAUTHN_ORIGIN=https://ag.example.com:8443 and WEBAUTHN_RP_ID=ag.example.com.

For a standard setup you don't edit .env by hand. The installer generates a complete, working configuration: it creates the security secrets (API key, session key) and the Web Push keys for you, so the box is fully functional out of the box — you can log in, control audio, browse the library and radio without touching any file. The flags above are simply the recommended way to set the two optional things they name (another address for passkeys, and your own push contact); skip them and everything else still works. To set them later, re-run the installer with the flag: an update keeps everything else.

Roon needs nothing here either: install Roon Bridge from the Audio Software page and authorize the extension once inside Roon. See 6. Outputs & engines → Roon.

Optional flags (ui installer)

Flag	What it does
`--https`	Serves the interface over HTTPS, with the box's own certificate, on port 443. What a new install chooses when you just press Enter.
`--http`	Serves it in plain HTTP, on port 8080 — for a box behind a reverse proxy that handles HTTPS (see below).
`--port 9000`	Another port: 80, 443, or from 1024 to 65535 — except the core's two ports when it runs on the same box (8000, and 8010, where it serves HQPlayer its radio stations), and in HTTPS 8081, where the box hands out its certificate.

Without them, a new install asks the two questions, and an existing one keeps its mode and its port without asking. So these flags are also how you change them later — re-run the installer with the one you want:

curl -fsSL https://audiogravity.app/install-ui.sh | sudo bash -s -- --http

--http or --https alone always means that mode's own port; add --port to choose another. The all-in-one installer takes them too.

They exist from version 0.9.75; an older installer refuses them. With one of those, uninstall the interface (sudo /var/www/audiogravity-ui/uninstall.sh), run its installer again without flags and answer 2 to the mode question.

A real domain — optional

On an iPhone or iPad, passkeys and push notifications work without one: on the box's name, with its own certificate trusted on the device (see 3. First run → Trust the box's certificate). A real domain adds two things: the app — passkeys included — from another network than the box's (a separate Wi-Fi or VLAN, where the box's name does not open), and no certificate to trust on each device — and it is the way on a device that refuses the box's own. The recipe that works well for a home box, without exposing anything to the internet:

A domain name you control (any cheap domain works), with a record pointing at the box's LAN address — e.g. ag.example.com → 192.168.1.30. The name only has to resolve on your network; nothing needs to be reachable from outside.
A real certificate via Let's Encrypt using the DNS-01 challenge (supported by certbot and most DNS providers' APIs) — it proves domain ownership through a DNS record, so no port needs opening to the internet.

A reverse proxy in front of Audiogravi^ty that terminates TLS — nginx, Caddy or Traefik, on the box itself or another always-on host. The proxy now owns TLS, so first switch the interface to plain HTTP — it then serves on port 8080, which also frees port 443 if the proxy runs on the box (see Optional flags (ui installer)):

curl -fsSL https://audiogravity.app/install-ui.sh | sudo bash -s -- --http

Then point the proxy at it:

server {
    listen 443 ssl;
    server_name ag.example.com;
    ssl_certificate     /etc/letsencrypt/live/ag.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ag.example.com/privkey.pem;
    location / {
        proxy_pass http://127.0.0.1:8080;    # the interface, in plain-HTTP mode
        proxy_set_header Host $host;
    }
}

(Proxy on another host? Use the box's LAN IP instead of 127.0.0.1.)

Tell Audiogravi^ty its public origin — re-run the core installer with --public-url https://ag.example.com (see the flags above). From then on, open the app through that URL: passkeys work from it, and only from it.

Caddy users get steps 2–3 in two lines (caddy obtains and renews certificates automatically). This is the standard self-hosting pattern — any guide on "Let's Encrypt DNS-01 + reverse proxy" applies as-is.

First contact

Open the address the installer prints at the end — the one its QR code carries: https://<name>.local. <name> is the first part of the box's hostname (musics → musics.local); lost it? Find your box's name. The box announces that name on the network, and unlike its address the name does not change when the router hands out a new lease, so it is the one to bookmark and the one to add the app from. Should it not open, the box's address, https://<box-ip>, is printed just below it. On an iPhone or iPad, trust the box's certificate first: 3. First run → 7.

When another device on your network already answers to that name, the box takes <name>-2.local, and the installer says so in yellow. Such a name is not one to keep: which of the two devices gets the -2 can change when they restart. Give the box a hostname of its own, then run the installer again — see 9. Troubleshooting. On first run, Audiogravi^ty activates a 30-day trial automatically — no action required — and you sign in with the default admin account (then change its password right away — see 3. First run). Continue to 3. First run.

Find your box's name

The box answers to <name>.local, where <name> is the first part of its hostname — musics.local for a box called musics, and for one called musics.1 too. The installer prints that address at the end. If you no longer have it, any of these gives it back:

Your router's list of connected devices shows the box under its hostname, with its address beside it.
In the app, opened at the box's address from your router's list — https://192.168.1.30, say: the System tab shows the Hostname. Signed in as an administrator, System › Actions › Support Report gives the exact address to type, under Web interface — Address https://192.168.1.30 · also https://musics.local.
On the box itself — keyboard and screen, or SSH — pgrep -a avahi shows the name between square brackets: [musics.local].

A box nobody renamed is raspberrypi.local on Raspberry Pi OS — unless it was given a name in Raspberry Pi Imager — and dietpi.local on DietPi. When another device of the network already answers to the name, the box takes the next free one, musics-2.local: the support report and pgrep -a avahi show it, the hostname alone does not.

Uninstalling

sudo /opt/audiogravity/uninstall.sh          # core — keeps your configuration
sudo /var/www/audiogravity-ui/uninstall.sh   # ui

This removes the services, the programs, the privileged rules Audiogravi^ty granted itself and its system account — but keeps your configuration in /etc/audiogravity (your signal-chain map, saved radio stations and licence), the backups of your audio services' configuration files in /var/backups/audiogravity, and the processor setting of the Performance page in /etc/cpu-governor.conf. Reinstalling afterwards picks up where you left off.

To remove those too, add --purge to the first command — in place of running it without, not after it: the uninstaller is removed with the programs, so there is no second run.

sudo /opt/audiogravity/uninstall.sh --purge  # core — removes your configuration too
sudo /var/www/audiogravity-ui/uninstall.sh   # ui

Already uninstalled without --purge? Remove what was kept yourself:

sudo rm -rf /etc/audiogravity /var/backups/audiogravity /etc/cpu-governor.conf

The interface's uninstaller also keeps the box's certificate authority, in /var/lib/audiogravity-ui, so that your devices still trust the box when you reinstall. To start from a new one, delete that directory too — each of your devices will then have to trust the new certificate (see 3. First run → Trust the box's certificate).

What is never removed, on purpose: the audio software itself — MPD, which came with the installer, and whatever you added from the Audio Software page (Shairport-Sync, upmpdcli, HQPlayer NAA, HQPlayer Embedded, Roon Bridge) — along with their own configuration files. They are ordinary system packages that keep working without Audiogravi^ty; remove them with your package manager if you want them gone.