Hosting Codec

Run Codec on Linux, at home or in the cloud. It needs space for your music and must stay on while you stream. Your phone connects to it; downloaded songs can play without it.

What you install

The server stores your music, artwork, playlists and playback state.
The web player comes in the same download. Open your server’s address in a browser.
The iPhone and iPad app connects to that address with your auth token.

There is no music catalog included. This project website is documentation, not your music server.

Install on Linux

Download the v0.2.0 Linux server release for your processor. The guided installer uses systemd and needs sudo. You can also run the same binary with your own service manager.

Choose your server’s processor type. Run uname -m: x86_64 means AMD64; aarch64 means ARM64.
- AMD64: server archive and checksum.
- ARM64: server archive and checksum.

Install the tools and download both files. Use your distribution’s package manager to install Python 3, CA certificates and curl.

Package commands for Debian and Ubuntu

sudo apt-get update
sudo apt-get install -y python3 ca-certificates curl

These download commands are for AMD64; replace amd64 with arm64 for ARM64.

curl -fLO https://github.com/urlocalgoose/codec/releases/download/v0.2.0/codec-server-v0.2.0-linux-amd64.tar.gz
curl -fLO https://github.com/urlocalgoose/codec/releases/download/v0.2.0/codec-server-v0.2.0-linux-amd64.tar.gz.sha256
sha256sum -c codec-server-v0.2.0-linux-amd64.tar.gz.sha256

Continue only if the checksum says OK.

Extract and install from the same directory.

tar -xzf codec-server-v0.2.0-linux-amd64.tar.gz
sudo ./codec-server-v0.2.0-linux-amd64/scripts/ubuntu-install.sh \
  ./codec-server-v0.2.0-linux-amd64.tar.gz \
  --sha256-file ./codec-server-v0.2.0-linux-amd64.tar.gz.sha256

The installer checks the package again, creates protected credentials, starts Codec and enables it at boot. The download includes the server and web player, ready to run.

Read your auth token in a private terminal. Save it in your password manager.
```
sudo /opt/codec/current/scripts/ubuntu-auth.sh
```
This displays the existing token. It does not reset it.

Run without the installer

The Linux binary also runs directly, including on distributions without systemd. Download, verify and extract the matching archive above. Set CODEC_AUTH_TOKEN in your service manager’s private environment configuration, then run this from the extracted directory:

./codec-sync-server \
  --addr 127.0.0.1:8787 \
  --data /path/to/codec-data \
  --web ./web

Replace the data path with a writable folder outside the extracted release. Keep it when updating, and use your distribution’s service manager to keep Codec running. The prebuilt server needs no Go, Rust, Bun or Node installation. An unset auth token leaves the API unprotected.

Connect at home or away

The installed server listens on 127.0.0.1:8787, accessible only from the server itself. A phone cannot use that address, even on the same Wi-Fi.

For private access, use Tailscale. Follow its setup guide on the server and your devices, connect them to the same private network, then run this on the server:

sudo tailscale serve --bg http://127.0.0.1:8787

Follow any HTTPS setup prompt. Tailscale Serve prints the HTTPS address to open in your browser or enter in Codec. Use the same auth token. Leave Tailscale running on both devices.

Use your own public domain instead

Install a reverse proxy such as Caddy, point your domain to the server and allow HTTPS traffic. The package includes deploy/ubuntu/Caddyfile.example; replace its example hostname with yours. It forwards requests to Codec on port 8787.

Keep public port 8787 closed and token protection enabled. A public connection needs HTTPS: plain HTTP does not encrypt credentials or music.

Add your music

Open your server’s HTTPS address, enter your token, then choose Settings → Import music. Select MP3s or a Loud bundle. Your other connected devices use that same library.

In Codec on iPhone or iPad, enter the same HTTPS address and token. Download music in the app before going offline.

Keep your library and credentials

With the guided installer, music, artwork and the database live in /var/lib/codec, and private configuration is in /etc/codec/codec.env. If you run Codec directly, keep the data folder and private environment configuration you chose. Keep both when updating. Neither belongs in the website files, and the data directory is not a watched music folder.

For a complete backup, stop Codec and copy its data and private configuration to backup storage, then restart it. With the guided installer, those folders are /var/lib/codec and /etc/codec. Do not copy only a live database or run two servers against the same data.

Updates and troubleshooting

For a guided installation, download a newer release’s matching archive and checksum. Run the installed updater with those two paths:

sudo /opt/codec/current/scripts/ubuntu-update.sh /path/to/codec-server-v0.2.0-linux-amd64.tar.gz \
  --sha256-file /path/to/codec-server-v0.2.0-linux-amd64.tar.gz.sha256

Adjust the architecture and paths to match the files you downloaded; keep their filenames unchanged. Updates preserve your library and token, with a brief service restart. The updater’s database backup does not replace a full music backup.

Check sudo systemctl status codec and sudo journalctl -u codec if the service will not start. For connection or playback help, see Support.

For a direct installation, stop Codec, back up its data and private configuration, then replace the executable and web files together. Start it with the same data path and token, and use your service manager’s logs to check startup.

All guides · The Loud format · Code reference