Direct Installation

SnapDog is distributed as lightweight native binaries. The current release workflow publishes Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64, aarch64) artifacts.

---

Operating System Requirements

Ensure your target machine meets the following requirements:

• Linux: Kernel 5.4 or higher. ALSA (Advanced Linux Sound Architecture) is required for local audio output interfaces.
• macOS: macOS 12 (Monterey) or higher.
• Windows: Windows 10/11 or Windows Server 2019+ (supported when running as a background service).

---

Package Managers

Arch Linux (AUR)

AUR helper tools can be used to install the latest pre-compiled binary or build SnapDog directly from the Arch User Repository.

# Install the server and audio client
yay -S snapdog snapdog-client

# Enable and start both services (the packages install their systemd units)
sudo systemctl enable --now snapdog snapdog-client

macOS (Homebrew)

For Apple Silicon or Intel Macs, we maintain a custom Homebrew tap:

# Tap the repository
brew tap snapdogrocks/tap

# Install the server and audio client
brew install snapdog snapdog-client

# Run SnapDog as a macOS background service
brew services start snapdog

Debian/Ubuntu (APT)

We distribute native .deb packages for Debian and Ubuntu architectures (amd64, arm64).

1. Fetch the archive keyring and check its fingerprint before trusting it:

   curl -fsSL https://deb.snapdog.cc/snapdog-archive-keyring.pgp \
     -o /tmp/snapdog-archive-keyring.pgp
   gpg --show-keys --with-colons /tmp/snapdog-archive-keyring.pgp \
     | awk -F: '$1 == "fpr" { print $10; exit }'
   # Expected: 1B7B79417383648BBFBE282E01AB8296EF0FCD76

   That is the certifying primary key; packages for this domain are signed by its subkey CFE7BACA652DD0D72EB7156FC7252FAD41F8F7DA.
2. Register the repository, bound to that key:

   sudo install -m 0644 /tmp/snapdog-archive-keyring.pgp \
     /usr/share/keyrings/snapdog-archive-keyring.pgp
   echo "deb [signed-by=/usr/share/keyrings/snapdog-archive-keyring.pgp] https://deb.snapdog.cc rolling main" \
     | sudo tee /etc/apt/sources.list.d/snapdog.list

3. Update package lists and install:

   sudo apt update
   sudo apt install snapdog snapdog-client

4. Enable and start both services. The packages install their own systemd units, so there is no unit file to write:

   sudo systemctl enable --now snapdog snapdog-client

Windows Service

SnapDog compiles to a native Windows binary (x86_64 and arm64) and can run as an NT Service.

1. Download the Windows binary (snapdog.exe) for your architecture and place it in C:\Program Files\SnapDog\.
2. Open a Command Prompt as Administrator and register the service:

   sc create SnapDog binPath= "\"C:\Program Files\SnapDog\snapdog.exe\" --service --config \"C:\ProgramData\snapdog\snapdog.toml\"" start= auto
   sc start SnapDog

---

Direct Binary Download

If you prefer to install the pre-compiled binaries manually:

1. Download the correct archive for your architecture from the GitHub Releases page.
2. Extract the archive and copy the binary to /usr/local/bin:

   tar -xzf snapdog-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz
   sudo mv snapdog /usr/local/bin/
   sudo chmod 755 /usr/local/bin/snapdog

---

Compiling from Source

If you want to compile SnapDog with custom target optimizations, you can build it from source using Cargo.

Note

Building from source allows choosing specific Snapcast server backends. See the compilation feature flags described in the Server Mode Selection section below.

Build Dependencies

Ensure your development machine has the required system libraries installed:

• Debian/Ubuntu: sudo apt install build-essential pkg-config clang libasound2-dev libavahi-compat-libdnssd-dev
• macOS: Xcode Command Line Tools are sufficient.

Building

1. Clone the repository:

   git clone https://github.com/SnapDogRocks/snapdog.git
   cd snapdog

2. Build the release binary:

   cargo build --release -p snapdog

3. The compiled binary will be available at target/release/snapdog.

---

Post-Installation Service Scripts

This section is only for the direct binary download and source builds. The AUR and APT packages install their own systemd units, and Homebrew runs SnapDog through brew services.

Caution

Do not add these files on a package install. A unit in /etc/systemd/system/ overrides the one the package installed, and this one points to /usr/local/bin instead of /usr/bin.

Linux Systemd Service Unit

Create /etc/systemd/system/snapdog.service. It matches the unit the packages ship, with the binary in /usr/local/bin:

[Unit]
Description=SnapDog multiroom audio server
After=network-online.target sound.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/snapdog --config /etc/snapdog/snapdog.toml
Restart=on-failure
RestartSec=5
DynamicUser=yes
SupplementaryGroups=audio
StateDirectory=snapdog
WorkingDirectory=/var/lib/snapdog
ConfigurationDirectory=snapdog
ProtectSystem=strict
ProtectHome=yes
NoNewPrivileges=yes
PrivateTmp=yes

[Install]
WantedBy=multi-user.target

Then load and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now snapdog

For the audio client, use snapdog-client.service from the repository the same way and change its ExecStart to /usr/local/bin/snapdog-client.

macOS Launchd Service Agent

Create ~/Library/LaunchAgents/cc.snapdog.server.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>cc.snapdog.server</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/snapdog</string>
        <string>--config</string>
        <string>/Users/Shared/snapdog.toml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

---

Server Mode Selection

SnapDog supports two primary Snapcast compilation backends. You can select the backend using Cargo feature flags:

• snapcast-embedded (Default & Recommended): Integrates the Snapcast server directly into the Rust daemon binary (leveraging our native Rust port of the original C++ Snapcast codebase via the snapcast-* crates). This mode is strongly recommended because it manages group synchronization inline, supports proprietary float PCM channels for parametric EQ corrections, and doesn’t require maintaining an external binary.
• snapcast-process: Spawns and manages a standalone C++ snapserver process in the background. Choose this only if you must rely on advanced C++ features or legacy external pipe encoders.

---

Next Steps

Configuration GuideCustomize zone topologies, client speaker volumes, and home automation triggers.

Docker ContainerDeploy SnapDog in a containerized environment.