The Island guide

A place to start.

Get the app running, bring Spotify along, and make it yours.

Get Island.

Currently available from source.

There are no published release downloads yet. The project includes packaging for macOS, Linux, and Windows; installers will appear on GitHub when a release is published.

Check releases

For the Spotify integration, use macOS 12 or later with Spotify Desktop. Install Rust 1.90 or later, Xcode Command Line Tools, and Python 3 before building.

Build and launch on macOS
git clone https://github.com/Sullivansome/island.git
cd island
./scripts/dev.sh --once

The command builds Island and its workspace plugins, then launches the app once. A normal development run loads the Spotify plugin directly from the workspace.

Build requirements ↗

Connect Spotify.

  1. Open Spotify Desktop.

    Start a song in the desktop app. The web player is not supported by this plugin.

  2. Allow Automation.

    When macOS asks, allow Island to control Spotify. If the strip says “Allow Automation,” open System Settings → Privacy & Security → Automation and enable Spotify access for Island or osascript.

  3. Return to your music.

    Restart Island if you changed the permission. The current lyric appears when synced lyrics are available. Right-click the Island to collapse it.

You don’t need a second Spotify login. Lyric lookups use your track’s information to search LRCLIB and NetEase.

Make My plugins yours.

Open Market… from Island’s menu-bar icon, or press ⌘ ⇧ M on macOS. Choose My plugins to see installed versions and runtime status.

Install a local plugin
Choose Install from folder…, select the folder containing island-plugin.toml and its executable, review its source and requested permissions, then approve.
Enable or disable
Open the plugin’s detail page and use Enable or Disable. Your choice is saved.
Update or remove
Review an available update before installing. When removing a plugin, you can keep its data for a later reinstall. Bundled plugins can be disabled.

Only install plugins you trust. Native plugins run with your OS user privileges; the permission list describes host capabilities, not a security sandbox.

When something needs attention.

“Plugin API 1 unsupported (host 2)”

The installed plugin was built for an older protocol. Replace both its manifest and executable with a compatible build. Changing the API number in the manifest does not update the code.

For this repository’s Spotify plugin, run these commands from the Island checkout:

Rebuild and replace the Spotify plugin
cargo build --workspace --locked
cargo run -p island-cli -- plugin install ./plugins/spotify

My plugins keeps incompatible packages visible as Needs update. You can replace one through Install from folder, or remove it. Replacing a package preserves its data and enabled setting.

Spotify says “Allow Automation”

Check Spotify access under System Settings → Privacy & Security → Automation. If access is already enabled, toggle it off and on, then restart Island and play a song.

No lyrics for the current track

Check the network connection and try another song. Synced lyrics depend on provider coverage and a matching track. Playback can be available even when lyrics are missing.

A plugin won’t start

Open its detail page in My plugins and read the reported error. Use Retry for a runtime failure, or install a compatible package if it says Needs update.

Report an issue ↗

Beyond macOS.

Island has a shared Rust core, a GPUI shell for macOS and Windows, and a native GTK shell for Linux. The Spotify plugin currently supports macOS only.

Linux uses GTK 3 and gtk-layer-shell on compatible Wayland compositors, or an X11 session. Windows builds require MSVC Build Tools. Installer and physical-display validation remain platform-specific.

Linux setup ↗All requirements ↗