Getting started

Getting started

Documentation home

Standalone downloads — no Python required

Open the latest release and download the archive for your computer under Assets. These are the 0.70.2 packages:

System	Download	Start
macOS, Apple Silicon	tagcast-0.70.2-macos-arm64.zip	Extract Tagcast.app, move it to Applications and open it.
macOS, Intel	tagcast-0.70.2-macos-x64.zip	Extract Tagcast.app, move it to Applications and open it.
Windows, x64	tagcast-0.70.2-windows-x64.zip	Extract the whole archive, then open Tagcast.exe in the extracted folder.
Linux, x64	tagcast-0.70.2-linux-x64.tar.gz	Extract with tar -xzf tagcast-0.70.2-linux-x64.tar.gz, then run ./Tagcast inside the extracted Tagcast folder.

On a Mac, About This Mac tells you whether you have an Apple chip or an Intel processor. Linux needs a graphical desktop and glibc 2.35 or newer. Keep the complete extracted Windows/Linux package together; keep the macOS app's Contents intact.

Tagcast opens in its own desktop window, with the same editor, player and queue as the Python/browser route. No separate browser, Python or Node.js installation is required. Closing the last window or choosing Quit stops the server it started, after accepted writes and read-back checks finish. An existing compatible server is reused and left running on Quit. Stop older Tagcast versions before upgrading.

The downloads are not Developer ID signed/notarized on macOS or Authenticode signed on Windows. If your operating system blocks opening one, use System Settings → Privacy & Security → Open Anyway on macOS, or More info → Run anyway on Windows.

Account settings, sign-in tokens, cache and local album favourites retain their normal ~/.tagcast/ folder. Electron has a separate Chromium profile: browser-local preferences and Change history are not automatically copied from Safari/Chrome/Brave. Audio outputs depend on Chromium and the operating system; Electron does not add Sonos or Safari's native AirPlay picker.

Each archive has a separate .sha256 checksum file under Assets. See the standalone guide for checksum verification, the bundled browser CLI and platform requirements. GitHub's Source code archives are for the source installation below.

Connect your iBroadcast account

Tagcast initially shows a demo library. To load your own collection:

1. Click Connect iBroadcast at the bottom of the left sidebar, or Demo · Connect at the top right. On a small screen, open the navigation menu to reach the sidebar controls.
2. If Use Tagcast sign-in appears, select it first. Choose Sign in with a code, then Open iBroadcast sign-in. Sign in on the iBroadcast website, enter the code if asked, and click Allow to grant the requested access.
3. After the authorization success message, return to the Tagcast window. The website's “return to your device” means return to Tagcast on this computer. Keep Tagcast open: it should show Loading library…, then Live and replace the demo with your own artists and albums. The first download of a large library can take a little while.

No client ID, client secret or redirect-URL setup is needed for this sign-in. See Connecting to iBroadcast for the complete steps and what to check if the demo remains.

Homebrew on macOS

Install the same standalone app through the Cyberdelia Homebrew tap:

brew install --cask cyberdeliaAI/apps/tagcast

Homebrew selects the Apple Silicon or Intel download, verifies its checksum and installs the app in Applications, with tagcast-cli available in your terminal. The first launch follows the same macOS security checks as the direct download. If you installed Tagcast manually, stop it and move the existing /Applications/Tagcast.app aside first; your separate settings stay in place.

For updates, stop Tagcast, run brew update, then brew upgrade --cask cyberdeliaAI/apps/tagcast. New releases become available after this tap's version and checksums are updated. See the tap guide for removal and maintenance.

Run from source with Python or uv

Download and extract Source code (zip) from the release, or clone this repository:

git clone https://github.com/cyberdeliaAI/tagcast.git
cd tagcast

You need uv or Python 3.11 or newer. In the extracted/cloned folder, start the script for your system:

System	Start script
macOS	Double-click start-tagcast.command (right-click → Open if macOS asks).
Windows	Double-click start-tagcast.bat.
Linux	Run ./start-tagcast.sh.

The scripts use uv when available. Otherwise they create a .venv beside the script and install Tagcast on the first start. Set TAGCAST_NO_UV=1 to use the Python fallback explicitly. Keep the terminal window open; Ctrl+C stops the server it started. Starting another copy opens the existing Tagcast.

Or run it directly from a terminal in the source folder:

With uv:

uv run --frozen tagcast --open

With Python on macOS/Linux:

python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/tagcast --open

With Python on Windows (PowerShell):

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\tagcast.exe --open

Use --port 8913 to choose another local port, for example uv run --frozen tagcast --port 8913 --open.

Updating Tagcast

Tagcast checks GitHub for a newer stable release at startup, at most once a day. A notification links to the release page. Use Settings → Tagcast updates to check immediately or disable automatic checks. No account credentials or library data are sent to GitHub. Updates are downloaded and installed manually.

1. Stop the old Tagcast first. Quit the desktop app/launcher, or stop its terminal server with Ctrl+C. Closing only the browser tab is not enough.
2. Download and extract the new package for your computer, then replace the old application/folder. Source users should update their checkout or use a freshly extracted source archive.
3. Start the new version. Your account settings, tokens and cache remain in ~/.tagcast/, or your configured TAGCAST_HOME. Reload the browser page if it still shows the old interface.

Electron reuses only a matching Tagcast version and host protocol. If an older server is still running, close it and retry. The small version beside Settings at the bottom of the sidebar tells you which version you are using.

Desktop and browser use

The Electron app requires macOS 13 Ventura or newer on Mac. Electron has its own Chromium profile, while server settings and local account favourites stay in the usual settings folder. See the desktop guide for sign-in, profiles and local builds.