# Cardinal Help Site

> Documentation for Cardinal Media Server, a headless self-hosted media server, and for building your own apps against its API. Also covers installing and operating the server, its bundled Music, Photos and Cinema web apps, and Cardinal's optional cloud services.

Every guide is available as Markdown by appending `.md` to its URL, as linked below. The documentation changes often: fetch pages fresh rather than relying on earlier copies. Instructions for AI agents are at https://help.cardinalapps.io/agents.md.

## DIY Apps

- [Build apps for Cardinal Media Server](https://help.cardinalapps.io/guides/diy-apps.md): The headless model, what you can build, and the guides
- [Authentication](https://help.cardinalapps.io/guides/diy-apps/authentication.md): Personal access tokens, password login, and token refresh
- [Connecting to a server](https://help.cardinalapps.io/guides/diy-apps/connecting-to-a-server.md): LAN addresses and Remote Access direct connections
- [Streaming and media](https://help.cardinalapps.io/guides/diy-apps/streaming-and-media.md): Browsing, audio streams, cover art, waveforms, and photos
- [Events](https://help.cardinalapps.io/guides/diy-apps/events.md): Real-time server-sent events
- [Web apps and CORS](https://help.cardinalapps.io/guides/diy-apps/web-apps-and-cors.md): What a browser app on its own domain needs
- [API reference](https://help.cardinalapps.io/guides/diy-apps/api-reference.md): Where the OpenAPI specification is, and the API's conventions
- [Building with a coding agent](https://help.cardinalapps.io/guides/diy-apps/building-with-a-coding-agent.md): The app-building skill and machine-readable resources
- [Recipes](https://help.cardinalapps.io/guides/diy-apps/recipes.md): Rules and reference TypeScript for the behaviour Cardinal's own apps implement
- [Recipe: Connecting and staying connected](https://help.cardinalapps.io/guides/diy-apps/recipes/connecting-and-staying-connected.md): Remembered address, candidate walk, re-resolving, and moving to a new address
- [Recipe: Playback and the queue](https://help.cardinalapps.io/guides/diy-apps/recipes/playback-and-the-queue.md): Server-side queues, stream URLs, play history, and resuming after a move
- [Recipe: Live updates with events](https://help.cardinalapps.io/guides/diy-apps/recipes/live-updates-with-events.md): The event stream loop, reconnection, and what to refresh for each event
- [Recipe: Permissions in the UI](https://help.cardinalapps.io/guides/diy-apps/recipes/permissions-in-the-ui.md): Roles, capabilities, gating controls, and handling 403
- [OpenAPI specification](https://help.cardinalapps.io/openapi/media-server.json): The Media Server API, generated from its source code

## Skills

- [Build a Cardinal app](https://cardinalapps.io/skills/build-a-cardinal-app.md): One-time setup of a new app on Cardinal, connected and health-checked against the developer's own server
- [Install with Docker](https://help.cardinalapps.io/skills/install-cardinal-media-server-with-docker.md): Guided installation with Docker Compose
- [Install with Proxmox](https://help.cardinalapps.io/skills/install-cardinal-media-server-with-proxmox.md): Guided installation on Proxmox VE
- [Update with Docker](https://help.cardinalapps.io/skills/update-cardinal-media-server-with-docker.md): Guided update with rollback
- [Update with Proxmox](https://help.cardinalapps.io/skills/update-cardinal-media-server-with-proxmox.md): One-command update with rollback
- [Uninstall with Docker](https://help.cardinalapps.io/skills/uninstall-cardinal-media-server-with-docker.md): Guided removal; erases the server's database, never media files

## Install and operate

- [Install with Docker](https://help.cardinalapps.io/guides/quick-start/install-with-docker.md): Docker Compose templates for SQLite and PostgreSQL
- [Install with Proxmox](https://help.cardinalapps.io/guides/quick-start/install-with-proxmox.md): Install as a Proxmox VE application container
- [Deployment](https://help.cardinalapps.io/guides/deployment.md): Checklist to optimize and harden a server before going live
- [Environment variables](https://help.cardinalapps.io/guides/cardinal-media-server/environment-variables.md): Configuring the server with environment variables
- [Accounts](https://help.cardinalapps.io/guides/cardinal-media-server/accounts.md): Cloud and local accounts, the Guest Account, and sessions
- [Role-Based Access Control](https://help.cardinalapps.io/guides/cardinal-media-server/role-based-access-control.md): Roles and capabilities
- [Libraries](https://help.cardinalapps.io/guides/cardinal-media-server/libraries.md): Grouping media by folder to filter it across the apps
- [Indexing](https://help.cardinalapps.io/guides/cardinal-media-server/indexing.md): Indexing media files, with pages for [music](https://help.cardinalapps.io/guides/cardinal-media-server/indexing/music.md) and [photos](https://help.cardinalapps.io/guides/cardinal-media-server/indexing/photos.md)
- [Jobs](https://help.cardinalapps.io/guides/cardinal-media-server/jobs.md): Background jobs such as thumbnails and waveforms
- [Release channels](https://help.cardinalapps.io/guides/cardinal-media-server/release-channels.md): The available release channels and how to choose one
- [Custom domains](https://help.cardinalapps.io/guides/cardinal-media-server/custom-domain.md): Running the server at a domain you own
- [Uninstall](https://help.cardinalapps.io/guides/cardinal-media-server/uninstall.md): Removing the server

## Apps

- [Music playback](https://help.cardinalapps.io/guides/cardinal-music/music-playback.md): How Cardinal Music plays audio
- [Queues](https://help.cardinalapps.io/guides/cardinal-music/queues.md): Dynamic and static playback queues
- [Tracks](https://help.cardinalapps.io/guides/cardinal-music/music-tracks.md), [Releases](https://help.cardinalapps.io/guides/cardinal-music/music-releases.md), [Artists](https://help.cardinalapps.io/guides/cardinal-music/music-artists.md): Browsing music
- [Ratings](https://help.cardinalapps.io/guides/cardinal-media-server/ratings.md): Ratings and favorites
- [Photo metadata](https://help.cardinalapps.io/guides/cardinal-photos/photo-metadata.md): The photo metadata saved during indexing
- [Viewing HEIF/HEIC images](https://help.cardinalapps.io/guides/cardinal-photos/viewing-heic-images.md): Viewing HEIC photos on devices without native support

## Cloud services

- [Remote Access](https://help.cardinalapps.io/guides/cloud-services/remote-access.md): Reaching a server from anywhere, with pages on [direct connections](https://help.cardinalapps.io/guides/cloud-services/remote-access/direct-connection.md), the [relay](https://help.cardinalapps.io/guides/cloud-services/remote-access/relay-connection.md), [cloud-hosted apps](https://help.cardinalapps.io/guides/cloud-services/remote-access/cloud-hosted-apps.md), and [troubleshooting](https://help.cardinalapps.io/guides/cloud-services/remote-access/troubleshooting.md)
- [Secure Backups](https://help.cardinalapps.io/guides/cloud-services/backups.md): Cloud backups, with pages on [restoring](https://help.cardinalapps.io/guides/cloud-services/backups/restoring.md), [security](https://help.cardinalapps.io/guides/cloud-services/backups/security.md), and [retention](https://help.cardinalapps.io/guides/cloud-services/backups/deletion-and-retention.md)
- [Uptime](https://help.cardinalapps.io/guides/cloud-services/uptime.md): Downtime alerts for a server

## Optional

- [Telemetry](https://help.cardinalapps.io/guides/cardinal-media-server/telemetry.md): The anonymous usage data Cardinal collects with consent
- [Keyboard shortcuts](https://help.cardinalapps.io/guides/cardinal-media-server/keyboard-shortcuts.md): Keyboard shortcuts in the bundled apps
- [Album art thumbnails](https://help.cardinalapps.io/guides/cardinal-media-server/jobs/album-art-thumbnails.md), [Generate waveforms](https://help.cardinalapps.io/guides/cardinal-media-server/jobs/generate-waveforms.md), [Photo thumbnails](https://help.cardinalapps.io/guides/cardinal-media-server/jobs/photo-thumbnails.md), [Photo variations](https://help.cardinalapps.io/guides/cardinal-media-server/jobs/photo-variations.md): Individual jobs
- [Sitemap](https://help.cardinalapps.io/sitemap.xml): Every page on the site