Documentation

Run Hades with confidence.

Install your server, connect your services, give people access, and keep everything working.

Updated September 10, 2026 · Current beta guides

What Hades does

Hades is a self-hosted server that brings your media services, metadata, and user access together. Administrators manage it in a web browser. Icarus connects to it in Hades mode for a personal media experience.

You supply the media services and the machine running Hades. Hades does not supply media, replace your download clients, or grant Plex access. It can be used through its administrator web dashboard without Icarus.

Icarus platforms: iPhone, iPad, Mac, and Apple Vision Pro use the Icarus iOS app family, which supports both standalone Icarus mode and Hades mode. The current Apple TV (tvOS) beta requires Hades pairing. See the Icarus guides for device instructions.

Use a current Hades release and the Icarus build intended for it. Beta features and service capabilities may differ from an older App Store build. These guides describe the current beta experience.

Before you start

A machine with Docker and Docker Compose, persistent storage, and permission to create a container.
A writable host directory for /config. This contains the server identity, database, and configuration that must survive container replacement.
Port 8124 available on the host, or an alternative host port mapped to container port 8124.
Service URLs and the credentials required by the integrations you want to connect.
A network route from Hades to those services, and from each Icarus device to Hades.

Set up and test on a trusted local network first. Use the correct host user and group IDs for your storage permissions. The values below are examples, not universal defaults.

Install with Docker Compose

Create a directory for the Compose file and a persistent config directory on the Docker host. In this example the config directory is /docker/Hades/config.
Save the following as compose.yaml. Change the host path, user/group IDs, and timezone to match your machine. Make sure the selected user can write to the config directory.

services:
  hades:
    image: docker.io/mypantheon/hades-server:latest
    container_name: Hades
    user: "1000:100"
    environment:
      - TZ=America/Los_Angeles
      - HADES_CATALOG_WORK_PROFILE=balanced
      - HADES_LOCAL_RECOVERY_ENABLED=false
      # Optional: enable recovery above and uncomment the password below.
      # - HADES_LOCAL_RECOVERY_PASSWORD=${HADES_LOCAL_RECOVERY_PASSWORD:?Set a recovery password in .env}
    volumes:
      - /docker/Hades/config:/config
    ports:
      - "8124:8124"
    restart: unless-stopped

Choose a catalog work profile

HADES_CATALOG_WORK_PROFILE controls how Hades paces catalog work. Use one of these exact, case-sensitive values:

balanced — the default. A practical starting point for routine use, balancing progress with time for other work on the host.
lowImpact — gentler pacing and longer pauses between background checks. Useful on a shared or resource-constrained host; indexing and maintenance can take longer.
fast — removes the profile’s extra CPU pacing and checks for work more often. Useful when prioritizing catalog progress and the host has resources available.

If the option is absent or unrecognized, Hades uses balanced. This setting is cooperative pacing, not a hard CPU or memory limit. Use Docker resource limits when you need an enforced ceiling.

Optional local recovery password

Recovery is disabled in the example. To enable it, set HADES_LOCAL_RECOVERY_ENABLED=true and uncomment the HADES_LOCAL_RECOVERY_PASSWORD line. Both an enabled flag and a non-empty password are required.

Create a .env file next to compose.yaml with the following entry, replacing the placeholder with your own long, unique password. Keep this file private and out of version control. Single quotes preserve literal characters such as dollar signs in the password.

HADES_LOCAL_RECOVERY_PASSWORD='YOUR_OWN_LONG_UNIQUE_PASSWORD'

The ${HADES_LOCAL_RECOVERY_PASSWORD:?...} expression in the Compose example refuses to start with a missing or empty password when that line is enabled. Leave the line commented and the flag set to false if you do not need recovery.

After first-run setup is complete and an administrator account exists, use the recovery option on the Hades sign-in screen and enter this password. It opens a one-hour administrator session without the normal Pantheon sign-in. It does not create the first owner, restore a missing database, or pair an Icarus device.

After changing the profile, recovery flag, or password, run docker compose up -d hades to recreate the service with the updated environment. A plain container restart does not apply changes from the Compose file or .env. To disable future recovery logins, set the flag to false, remove or comment the password line, and recreate the service.

From the directory containing compose.yaml, start Hades:

docker compose up -d
docker compose ps

Open http://YOUR_DOCKER_HOST:8124 in a browser, replacing the placeholder with the Docker host’s address. On that same host, http://127.0.0.1:8124 works. On another device, localhost points to that device instead.

If the container stops, inspect its startup logs before changing configuration:

docker compose logs --tail=100 hades

Check for a port conflict, an unwritable config directory, or a failed image pull. Keep the persistent directory when recreating the container.

Complete first-run setup

Open the Hades web address and complete the first-run owner setup presented by your build. Keep any local owner or recovery credentials in a password manager.
Complete the Pantheon sign-in and server linking steps if you want account-linked Icarus access. Use the intended Apple/Pantheon account consistently.
Review the server address used for Icarus connections. Use an address reachable by the devices that will connect; a Docker-only hostname is not usually reachable by a phone or Apple TV.
Add and test at least one service in Connections.
Confirm that Home shows the service state, then allow the initial library refresh to finish before investigating missing items.

If an existing server unexpectedly shows first-run setup again, stop and check the /config mount. An empty or incorrect host directory can make an existing installation look like a new server. Restore the original mount before creating another identity.

Find your way around the dashboard

The Hades web dashboard is for administrators. Standard users use their personal Hades access through Icarus; they do not receive the administrator dashboard simply by signing in.

Home: server state, work in progress, and items needing attention.
Library: media Hades has indexed from connected services.
Metadata: metadata sources and library issues that need review.
Connections: services and how Icarus reaches Hades.
People: invitations and user access.
Activity: running work, recent results, and notifications.
Settings: server, calendar, and Icarus connection settings.
Support & diagnostics: details and logs for investigating a problem.

Use the labels offered by your installed build. Some controls depend on the service and its capabilities.

Add and maintain service connections

Open Connections and choose the service type offered by your build.
Give the service a recognizable name. Enter its full base URL, including http:// or https://, any port, and any proxy base path.
Provide the API key or sign-in required by that service. Add custom headers only when your proxy or authentication gateway requires them.
Test the connection where offered, then save. Confirm the service’s health and data in Hades before testing Icarus.
Review which users may access the service and which actions they may perform.

A connection test proves that Hades can contact the service with the supplied credentials. It does not prove that every Icarus user has access, that every library item has been indexed, or that a playback device can reach a media server.

Manage Hades-supplied addresses and credentials here. After changes, refresh the Hades connection in Icarus. Creating a second standalone connection in Icarus can hide the underlying issue and show the service twice.

Choose supported services from the current connection picker. Media managers, download clients, request services, media servers, subtitles, and metadata providers serve different roles; connecting one does not automatically configure the others.

Connect Plex and verify playback access

Use the Plex connection flow in Connections to sign in and select a Plex server your account can access. Allow the sign-in window if the browser blocks it, and return to Hades to finish selecting and saving the server.

Hades administrator access and Plex library access are separate. An Icarus user may need to sign in to Plex or choose Verify Plex Access with a Plex account that can use the selected server.

If a Plex sign-in notification appears during an intentional connection or verification attempt, compare its timestamp with your attempt. Investigate unexpected account activity through Plex’s own account controls.

If metadata loads but playback fails, test the selected Plex server from the playback device. Check Plex remote access, server sharing, and any player requirements; a working Hades API connection does not guarantee a working Plex playback route.

Invite people and set permissions

Open People to invite users and review their access. Use an administrator account only for people who should manage server configuration and other users.

Create an invitation using the controls provided by your build and choose the intended access.
Have the recipient complete the invitation with the Apple/Pantheon identity they will use in Icarus.
Review the resulting user and service access in People.
Ask them to connect Icarus and confirm that the expected library and permitted actions are available.

Hide My Email may produce an Apple relay address. Confirm the linked account rather than assuming that a familiar display name or everyday email identifies it.

A user can be allowed to view a service without being allowed to change it. Missing or denied request, search, or management actions can be a permissions issue even when browsing works.

When someone should lose access, revoke it through the available user or device controls. Unpairing one Apple TV disconnects that device; it does not remove the user’s other devices or their server account.

Connect Icarus on iPhone, iPad, Mac, or Vision Pro

Install or update Icarus to the build intended for your Hades release.
Select Use Hades in onboarding, or open Settings > Hades in an existing Icarus setup.
Sign in with the Apple account associated with the user’s Pantheon and Hades access, then complete the offered server connection flow.
If prompted, choose Use Hades (recommended) or Keep both setups. Keeping both can display standalone and managed connections to the same service.
Confirm the Hades status in Settings and open a library item or service. Verify playback separately if you use Plex.

Icarus mode remains available on this app family for direct standalone connections. The iOS instructions apply to iPad, Mac, and Vision Pro, with layout and system-control differences. See the full Icarus documentation.

Pair Apple TV

The current Icarus tvOS beta requires Hades. Set up the services and the user’s access before opening Icarus on Apple TV.

On the Pair with Hades screen, scan the QR code with a phone or visit the exact address displayed.
Sign in with the intended Apple/Pantheon account. Enter the TV’s current code if asked and approve the connection.
Leave Icarus open on the TV while it waits for approval and loads the server.

Use Get a New Code if the timer expires. Approval on the phone does not prove that Apple TV can reach Hades; test the TV’s network route if content fails to load.

Older standalone tvOS configuration is retired in the current beta. Recreate the needed services in Hades before pairing. On the TV, Settings > Unpair from Hades disconnects only that TV.

Library, metadata, and requests

Hades builds its catalog from connected sources. The initial refresh may take time. Check Activity for ongoing work and service health before assuming the catalog is incomplete.

A title may exist in more than one provider. Review the source and available version before changing a title or diagnosing a duplicate. Use Metadata to review matching issues and provider state when artwork or title information is incomplete.

Metadata providers describe media; they do not supply the media files. Check provider credentials and status separately from download and playback services.

A request being accepted is different from approval, download, import, and playable availability. Follow the request provider and downstream service state. Do not submit duplicates while a request is processing.

If something is missing in Icarus, first confirm it in the original service, then in Hades, then check the user’s access. If only an action is missing, review permissions and provider capabilities.

Local and remote networking

Hades to services: addresses must work from inside the Hades container. Localhost and 127.0.0.1 refer to that container. Use a reachable host address or a service name on a shared Docker network.

Icarus to Hades: use an address reachable from the actual device. A private LAN address or local hostname generally needs the same network or an appropriately configured VPN.

Playback device to media server: Plex and other playback routes may need separate reachability and provider access.

Pantheon sign-in and device pairing authorize a connection. They do not create a VPN, port forward, or tunnel. Test from an external network before relying on access while traveling.

If you use a reverse proxy, configure a valid HTTPS certificate, the correct base path, and any supported required headers. Check that the proxy allows the API traffic used by Icarus. Fix certificate and routing errors at their source.

Changing the host port changes the address devices use; the container still listens on 8124 in the example. Limit exposure to the networks and users you intend to serve. See Security for additional guidance.

Back up and restore Hades

The persistent /config directory is the essential server backup. Keep the complete directory, its permissions, and the Compose configuration. It contains sensitive identity and service data; store backups privately.

For a consistent filesystem copy, schedule a brief outage, stop Hades, copy the complete config directory to your backup destination using your usual backup tool, then restart Hades. Do not copy only a live SQLite database file while leaving its related files behind.

docker compose stop hades
# Back up the complete host directory mounted at /config here.
docker compose start hades

Verify that the backup actually exists and can be read. Keep a copy outside the original storage device. Record the Hades image version or digest and the date alongside the backup.

Restore: stop Hades, preserve the current config as a separate recovery copy, restore the complete chosen backup to the mounted directory, restore ownership/permissions, and start a compatible Hades version. Check server identity, user access, connections, and the library before reopening access.

Hades configuration backups do not back up the media files or the databases of Sonarr, Radarr, Plex, and other services. Back up those separately. Icarus iCloud settings backups do not replace a Hades server backup.

Update and recover safely

Read the release notes for compatibility and migration changes. Record the running image version or digest.
Create and verify a consistent backup of /config and your Compose configuration.
From the Compose directory, pull and recreate the Hades service:

docker compose pull hades
docker compose up -d hades
docker compose ps
docker compose logs --tail=100 hades

Confirm the server version, sign-in, service health, and a representative Icarus connection after the update. Recreating the container with the same persistent mount retains the server data.

If an update fails, keep the logs and the pre-update backup. A database migration may make a simple image downgrade unsafe. Follow the release’s recovery guidance; restoring a compatible older image can also require restoring its matching pre-update config backup.

Do not delete the config directory or volumes to troubleshoot an update. Reinstalling the image alone cannot recover an erased server identity.

Troubleshoot by symptom

The web dashboard will not open: Check container status and startup logs, the host address and mapped port, and firewall access. Test from the Docker host and then from another device to separate startup from network problems.
First-run setup appears on an existing installation: Check the host directory mounted at /config and its contents. Restore the original mount or backup before creating a new owner.
A service cannot connect: Test its URL from Hades’s network. Check API credentials, base path, required headers, service health, and certificate validity.
A user cannot open the web dashboard: The dashboard requires administrator access. Standard users should connect with Icarus. Check People when the intended account has the wrong access.
Icarus does not offer the server: Check server linking, invitation completion, and the Apple/Pantheon account in use. A display name alone is not an account match.
Pairing approves, but Icarus will not load: Check the address delivered to the device and its network route. Generate a new TV code if the current one expired.
Media or actions are missing: Check the source service, refresh activity, account permissions, and provider capabilities in that order.
Plex browses but will not play: Verify the user’s Plex access and the media server route from the playback device.

For local health checks from the Docker host, the example deployment exposes:

curl --fail http://127.0.0.1:8124/health
curl --fail http://127.0.0.1:8124/version

A responding health endpoint shows that the server answers; it does not prove all services or accounts are healthy. Check Home, Connections, and Activity for that detail.

Get useful support

Include the Hades version or image tag, affected service, exact error and timestamp, recent changes, and whether the problem occurs locally or remotely. For Icarus, include its version/build, device, and operating system.

Describe what worked, what you selected, and what happened. Use Support & diagnostics and Activity to find relevant details. A short reproduction is often more useful than a large unfiltered log.

Remove API keys, tokens, passwords, cookies, custom authorization headers, webhook URLs, private addresses, and personal details before sharing. Never upload the complete config directory publicly.

Use Hades support for current contact and community options. For Icarus setup and in-app controls, use the Icarus documentation.