Apollo documentation

Operate the stack. Build against it.

These docs are organized for real use. Start with setup, read the architecture section if you want context, and use the reference sections when you need exact routes, hooks, or examples.

Start here Server repo Plugin source
Permanent anchors Sticky section nav Search with / Copyable commands
Apollo Docs /docs Quickstart + reference + plugins

Best starting points

Use the shortest path that matches the job.

This page brings Apollo's public documentation into one place: setup for first run, architecture for context, reference for the server, and plugin docs for client extensions.

First run

Quickstart + install matrix

Use this if you are setting up Apollo for the first time.

Integration

Server API overview

Use this when you need auth, search, playlists, or media details.

Extension

Plugin runtime

Use this to build client-side tabs, services, and event hooks.

Quickstart

Get Apollo running fast.

Apollo is a split stack. The server owns tracks, downloads, playlists, streams, and the local API. The client is the desktop app. If you only remember one rule, it is this: start the server first, then point the client at it.

Step 1

Run Apollo Server

Windows has a packaged build today. Linux currently runs from source with Node.js, yt-dlp, and ffmpeg.

Step 2

Connect Apollo Client

Install the Windows client or run the desktop app from source. If the server is remote, set APOLLO_SERVER_URL.

Step 3

Add plugins later

Apollo is usable without plugins. Add them when you need custom tabs, lyrics providers, or client automation.

Source path: server 
git clone https://github.com/ProtonDev-sys/apollo.git
cd apollo
npm install
npm start
Source path: client 
git clone https://github.com/ProtonDev-sys/apollo-client.git
cd apollo-client
npm install
npm start
Latest details: packaged releases and the most up-to-date setup instructions still live in the server releases, client releases, and their READMEs.

Explanation

Architecture map

Apollo follows a clean boundary that makes the rest of the docs easier to navigate. Server docs are about library ownership, media handling, and downloads. Client docs are about playback and the UI. Plugin docs are about extending the client safely.

Server

API + downloads + storage

Tracks, playlists, downloads, health, auth, and media delivery.

Client

Playback + browsing

Authentication, search UI, library views, and desktop control.

Plugins

Client extensions

Detail tabs, lyrics providers, and host event integrations.

Local HTTP API Desktop Electron client Trusted plugin runtime Downloads via yt-dlp + ffmpeg

Install matrix

Current paths by platform

Apollo does not offer the same install path on every platform, so this section spells out what is available right now.

Platform Client Server Status
Windows Packaged build or source path Packaged build or source path Best current path
Linux Source path Source path Supported, but more manual
Android No client build yet Not a server target Not available yet
iOS / iPadOS No client build yet Not a server target Not available yet
Windows server prerequisites 
winget install OpenJS.NodeJS.LTS
winget install yt-dlp.yt-dlp
winget install Gyan.FFmpeg.Essentials

Reference

Server reference

Apollo Server exposes a local HTTP API for health, auth, library queries, search, playback resolution, playlists, downloads, and media delivery. Think of this section as an API overview rather than a full schema reference.

Family Typical paths Purpose
Health + auth /api/health, /api/auth/status, /api/auth/session Check runtime state and establish a bearer session.
Library + search /api/tracks, /api/search, /api/artists Read your indexed library and search results from connected providers.
Playback + streams /api/playback/*, /media/* Resolve what should play and serve the media files.
Downloads /api/downloads/* Queue downloads and track their progress.
Playlists /api/playlists/* Create, update, reorder, and manage playlists.
Base URL: http://127.0.0.1:4848 is the documented local default used by Apollo's public examples.

Reference

Auth and sessions

The common flow is straightforward: detect whether auth is enabled, exchange the shared secret for a bearer token, then use that token on later requests. Revoke the session explicitly when the client signs out.

  • Call GET /api/auth/status to discover auth state.
  • Send the shared secret to POST /api/auth/session.
  • Use Authorization: Bearer <token> on protected requests.
  • Invalidate the current session with DELETE /api/auth/session.
Create a session 
POST /api/auth/session
Content-Type: application/json

{
  "secret": "replace-this-with-the-shared-secret"
}

Reference

Downloads and playback

Downloads and playback are related, but they are not the same thing. Keep them separate in your tooling and your UI.

Downloads

Queue and inspect jobs

Use downloads endpoints for job state, progress, and retries.

Playback

Resolve on demand

Use playback endpoints when the client needs a file or stream to play.

Media

Stream the result

Use media endpoints to serve the file or stream after playback is resolved.

yt-dlp ffmpeg Queue state Playable source resolution

Reference

Playlists and media

Playlists are saved library data. Media endpoints are about serving files and streams. Keeping those separate makes client code easier to reason about.

  • Create and rename playlists through playlist-specific routes.
  • Add, remove, and reorder tracks without assuming media paths are stable IDs.
  • Handle artwork as playlist data, not as part of file delivery.
  • Use media routes for bytes and streams only after higher-level entities are resolved.

Plugin docs

Plugin development

Apollo Client plugins are trusted extensions. They can register UI sections, consume runtime APIs, and participate in app workflows, which means plugin docs need to be explicit about boundaries and cleanup expectations.

Minimal plugin shape 
export default {
  id: "example-plugin",
  name: "Example Plugin",
  async setup(api) {
    api.registerDetailTab({
      id: "example-tab",
      label: "Example",
      order: 30,
      mount({ container }) {
        container.textContent = "Apollo plugin panel";
      }
    });
  }
};

What plugins should own

  • Client-side UI additions and focused workflow improvements.
  • Lyrics resolution, detail tabs, and event-driven host automation.
  • Cleanup for listeners, timers, and any mounted UI state.

Plugin docs

Plugin runtime

The runtime is built around a few clear parts: setup APIs for registration, context objects for mounted detail views, and helper services for things like lyrics and events.

Runtime part Use it for
setup(api) Register detail tabs, providers, listeners, and host integrations.
mount({ container, context, services }) Render tab UI and consume playback or selection context.
services.resolveLyrics(track) Resolve synced or plain-text lyrics through the app's lyrics system.
services.emit / services.on Coordinate with host-level events without reaching into internals directly.
Safety rule: Apollo plugins are trusted code. If a plugin changes state in the wrong place or leaks listeners, it can break rendering, playback, or persistence.

Plugin docs

Plugin events and cleanup

Host events let plugins react without polling. Cleanup matters as much as registration because Apollo is a long-lived desktop app, not a disposable page load.

plugins:loaded app:ready selection:changed detail:tab-change library:refresh:success playback:track-changed auth:changed
Cleanup pattern 
async setup(api) {
  const off = api.on("selection:changed", refreshView);
  const timer = setInterval(refreshView, 5000);

  return () => {
    off?.();
    clearInterval(timer);
  };
}

Operations

Troubleshooting

Most first-run issues reduce to one of four causes: the server is not running, the client is pointed at the wrong URL, required download tooling is missing, or auth/session state is stale.

  • Verify Apollo Server is reachable before opening Apollo Client.
  • On source installs, confirm Node.js dependencies finished installing cleanly.
  • If downloads fail, re-check yt-dlp and ffmpeg.
  • If sign-in loops, clear the current session and create a new bearer token.
  • If a plugin behaves oddly, remove listeners and timers before blaming the host.
Search Apollo docs