Hosting Codec

Run Codec on an Ubuntu server 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 Ubuntu

These instructions use the v0.1.7 Linux server release. Use a normal Ubuntu installation with systemd and an account that can run sudo.

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.

Download both files on the server. These commands are for AMD64; replace amd64 with arm64 for ARM64.

sudo apt-get update
sudo apt-get install -y python3 ca-certificates curl
curl -fLO https://github.com/urlocalgoose/codec/releases/download/v0.1.7/codec-server-v0.1.7-linux-amd64.tar.gz
curl -fLO https://github.com/urlocalgoose/codec/releases/download/v0.1.7/codec-server-v0.1.7-linux-amd64.tar.gz.sha256
sha256sum -c codec-server-v0.1.7-linux-amd64.tar.gz.sha256

Continue only if the checksum says OK.

Extract and install from the same directory.

tar -xzf codec-server-v0.1.7-linux-amd64.tar.gz
sudo ./codec-server-v0.1.7-linux-amd64/scripts/ubuntu-install.sh \
  ./codec-server-v0.1.7-linux-amd64.tar.gz \
  --sha256-file ./codec-server-v0.1.7-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.

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

Music, artwork and the database live in /var/lib/codec. The private configuration is /etc/codec/codec.env. 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, copy /var/lib/codec and /etc/codec to protected backup storage, then restart it. Do not copy only a live database or run two servers against the same data.

Updates and troubleshooting

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-VERSION-linux-amd64.tar.gz \
  --sha256-file /path/to/codec-server-VERSION-linux-amd64.tar.gz.sha256

Replace VERSION, the architecture and paths with 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.

All guides · The Loud format · Code reference