Use an AI agent
Have your AI agent handle this for you with this skill.
Build an app
Build your own apps
Cardinal Media Server is a headless, self-hosted media server. It indexes the media on your own hardware and serves it over an HTTP API. Every client is a consumer of that API, including the Music, Photos, Cinema, and Admin web apps that ship with the server. Those bundled apps are reference clients: an app you build calls the same endpoints, under the same role-based permissions.
With a Remote Access direct connection, an app you build can reach the same server from outside your network.
What you can build
- A native music player for a platform the bundled apps do not cover.
- A photo frame, a dashboard, or a home-automation integration.
- A script that builds playlists, rates tracks, or reports on your library.
- A web app with a different interface for your own media.
The fastest path
Most apps for Cardinal are built with a coding agent such as Claude Code. Give your agent this prompt:
Fetch https://cardinalapps.io/skills/build-a-cardinal-app.md and follow it to help me build an app on Cardinal.
The skill asks what you want to build, checks your server, and sets up a new project that is connected to it, with a health check and an AGENTS.md your agent uses from then on. See Building with a coding agent.
How an app reaches your server
┌──────────┐ on your network ┌────────────────────────────────┐
│ │─────────────────────────────────▶│ Cardinal Media Server │
│ Your app │ │ │
│ │─────────────────────────────────▶│ /api/v1 REST │
└──────────┘ away: Remote Access direct │ /api/v1/events/subscribe SSE │
connection (HTTPS) │ /api/docs docs │
└────────────────────────────────┘
Fig. 1 — an app talks to the Media Server directly, on your network or through a Remote Access direct connection
Guides
| Guide | What it covers |
|---|---|
| Authentication | Personal access tokens, password login, and token refresh |
| Connecting to a server | Server URLs on your network, and finding a server through Remote Access |
| Streaming and media | Audio streams, cover art, waveforms, and photos |
| Events | Real-time server-sent events |
| Web apps and CORS | What a browser app needs from the server's owner |
| API reference | The OpenAPI specification and the conventions it follows |
| Building with a coding agent | The app-building skill and the machine-readable docs |
| Recipes | Rules and reference code for what Cardinal's own apps get right: connecting, playback and the queue, live updates, and permissions |
Cloud APIs
Cardinal's cloud services, such as Cardinal Account and the Remote Access relay, are not open to third-party apps yet. The guides in this section cover the Media Server's own API, plus the public Remote Access endpoint that finds a server's direct addresses.
License
Cardinal's self-hosted apps are licensed under the Freehold License. The license allows for anyone to fork, modify, and redistribute the code, but it does also come with a few important limitations that are outlined in the license. Commercial third party apps are allowed.
User privacy
All of Cardinal's own applications adhere to a strict Privacy Policy that outlines the rights that users have when it comes to their data. All third party applications must adhere to this Privacy Policy as well.
Getting help
Anyone building on Cardinal is welcome in the Developer Forum.
The self-hosted source code is on GitHub.
Was this article helpful?