Run a local ListenBrainz / Last.fm / Web Scrobbler compatible API (Rocksky CLI)

This guide explains how to start Rocksky’s local compatibility API on your machine, so you can use:

ListenBrainz-compatible clients (point them to your local server)

Last.fm-style scrobble clients (through the compat API)

Web Scrobbler (via a custom URL)

1. Prerequisites

Node.js installed (so you can run npx)

An AT Protocol account (handle or DID)

2. Set required environment variables

To keep stable credentials across restarts, you should export these variables before starting the server:

Compat API keys (required)

These must be set, otherwise they may be randomly generated on every start:

ROCKSKY_API_KEY

ROCKSKY_SHARED_SECRET

ROCKSKY_SESSION_KEY

ROCKSKY_WEBSCROBBLER_KEY

Example (macOS/Linux):

AT Protocol credentials (required to write to your PDS)

ROCKSKY_IDENTIFIER: your ATProto handle (e.g. you.bsky.social) or DID (e.g. did:plc:...)

ROCKSKY_PASSWORD: an app password (recommended), not your main password

Example:

Create an app password (Bluesky)

Go to: https://bsky.app/settings/app-passwords
Then: Settings → Privacy and Security → App passwords

3. Start the local compatibility server

Run:

Once started, your local compat API should be available at:

http://localhost:8778

4. Connect clients to your local API

a. ListenBrainz-compatible clients

Point your client to:
Base URL: http://localhost:8778

Use your ROCKSKY_API_KEY as the Authorization token (how you enter it depends on the client).

b. Web Scrobbler

Use the custom URL format:

http://localhost:8778/webscrobbler/<ROCKSKY_WEBSCROBBLER_KEY>

Example:

http://localhost:8778/webscrobbler/your_webscrobbler_key

c. Last.fm

Point your last.fm client to:

http://localhost:8778/2.0

Authentication

api_key: ROCKSKY_API_KEY

sk: ROCKSKY_SESSION_KEY

Legacy Last.fm API

Field	Value
Username	`ROCKSKY_API_KEY`
Password	`ROCKSKY_SHARED_SECRET`
Scrobble URL	http://localhost:8778

Notes & troubleshooting

First start may be slow: the server may take time the first time you run it because Rocksky CLI performs a local sync (especially if you already published many scrobbles).

After the initial sync: Rocksky CLI will write new scrobbles directly to your PDS, using ROCKSKY_IDENTIFIER + ROCKSKY_PASSWORD.

Run a local ListenBrainz / Last.fm / Web Scrobbler compatible API (Rocksky CLI)

1. Prerequisites#

2. Set required environment variables#

Compat API keys (required)#

AT Protocol credentials (required to write to your PDS)#

Create an app password (Bluesky)#

3. Start the local compatibility server#

4. Connect clients to your local API#

a. ListenBrainz-compatible clients#

b. Web Scrobbler#

c. Last.fm#

Notes & troubleshooting#