Upstream repo: https://github.com/plexinc/pms-docker
Plex Media Server organizes your personal video, music, and photo collections and streams them to Plex apps on phones, tablets, smart TVs, streaming devices, game consoles, and the web. This package wraps the official plexinc/pms-docker image and runs it on StartOS, keeping your media private and on hardware you control.
For end-user setup, see instructions.md. To build the package, see CONTRIBUTING.md.
- Image and Container Runtime
- Hardware Acceleration and Variants
- Volume and Data Layout
- Installation and First-Run Flow
- Configuration Management
- Network Access and Interfaces
- Actions (StartOS UI)
- Backups and Restore
- Health Checks
- Dependencies
- Limitations and Differences
- What Is Unchanged from Upstream
- Contributing
- Quick Reference for AI Consumers
| Property | Value |
|---|---|
| Image | plexinc/pms-docker (official) |
| Architectures | x86_64, aarch64 (GPU variants are x86_64 only) |
| Command | The image's own entrypoint (/init, s6-overlay), run as init |
The daemon passes PLEX_CLAIM as an environment variable only while a claim token is stored and the server is not yet linked; the image's first-run script exchanges it for a permanent token on startup.
The package publishes one variant per accelerator, all under a single version. StartOS offers the variant whose hardware requirement the host satisfies:
| Variant | Hardware requirement | Arch | Notes |
|---|---|---|---|
generic |
none (fallback) | x86_64, aarch64 | Software transcoding |
nvidia |
NVIDIA GPU | x86_64 | NVENC/NVDEC (NVIDIA container runtime) |
intel |
Intel GPU (i915) |
x86_64 | Quick Sync via /dev/dri |
amd |
AMD GPU (amdgpu) |
x86_64 | VAAPI via /dev/dri |
hardwareAcceleration is enabled, so StartOS exposes the matching GPU device to the container. Hardware transcoding additionally requires an active Plex Pass and must be turned on in Plex under Settings → Transcoder → Use hardware acceleration when available.
| Volume | Mount Point | Purpose |
|---|---|---|
config |
/config |
Plex database, metadata, and Preferences.xml |
transcode |
/transcode |
Transcoder temporary files |
startos |
(internal) | Package state (store.json): claim token, selected media sources |
Selected media sources are mounted read-only:
| Source | Mount Point |
|---|---|
| File Browser | /data/filebrowser |
| Nextcloud | /data/nextcloud |
The server must be claimed by a Plex account before it can be used. Plex normally claims a server the first time you open its web interface from localhost; StartOS serves the UI through a reverse proxy, where that local claim flow isn't available, so claiming is done headlessly with a claim token. Onboarding is therefore a single path, surfaced as a critical task after install:
Link a Plex account — run Link Plex Account and paste a claim token from https://plex.tv/claim (it expires 4 minutes after you generate it). Plex claims itself to your account automatically on startup; you then sign in normally from any Plex app or the web UI.
A second (also critical) task prompts you to select media sources.
Preferences.xml (on the config volume) is Plex's own settings file. The package manages only a few attributes through merge(), preserving everything Plex writes itself:
| Setting | Source | Applied |
|---|---|---|
FriendlyName |
Set Server Name action | On next start (action is stopped-only) |
PlexOnlineToken |
written by Plex after a successful claim | read-only to the package |
FriendlyName is written straight into Preferences.xml by the Set Server Name action, which is only runnable while Plex is stopped — Plex owns that file and rewrites it at runtime, so editing it is only safe when Plex isn't running. The claim token is stored in store.json and passed as PLEX_CLAIM until the server is linked. All other Plex settings are configured inside the Plex web UI.
| Interface | Port | Protocol | Path | Purpose |
|---|---|---|---|---|
| Web UI | 32400 | HTTP | /web |
Plex web interface |
Access methods:
- LAN IP with unique port
<hostname>.localwith unique port- Tor
.onionaddress - Custom domains (if configured)
Access to the web app is governed by Plex's own plex.tv sign-in; StartOS controls who can reach the interface.
| Action | Input | Availability | Purpose |
|---|---|---|---|
| Link Plex Account | Yes | any | Store a claim token; Plex links itself to the account automatically |
| Select Media Sources | Yes | any | Choose which services (File Browser, Nextcloud) Plex reads media from |
| Set Server Name | Yes | only-stopped | Set Plex's FriendlyName (written directly to Preferences.xml) |
Included in backup:
configvolume (Plex database, metadata, preferences)startosvolume (package state)
Excluded: transcode (temporary, regenerable) and media itself (lives in the source services). Restore behavior: volumes are restored before the service starts.
| Check | Method | Messages |
|---|---|---|
| Web UI | HTTP GET /identity (port 32400) |
Success: "The Plex web interface is ready" / Error: "The Plex web interface is not ready" |
/identity is Plex's unauthenticated readiness endpoint. The check requires a 2xx response (not merely any response): during first-run database migrations Plex answers with 503, so requiring a 2xx keeps the check from flipping "ready" until migrations finish. A 60-second grace period covers normal startup.
Both are optional and declared only when selected as a media source:
| Dependency | Version | Kind | Purpose |
|---|---|---|---|
| File Browser | >=2.63.2:0 | exists |
Read media from File Browser |
| Nextcloud | >=32.0.8:0 | exists |
Read media from Nextcloud |
- A Plex account is required (no account-free mode). Plex's web app authenticates against plex.tv regardless of any server-side setting, so the interface can't be used without signing in to a Plex account.
- The server must be claimed, via claim token. Separate from the account requirement: a Plex server must be claimed (made owned by an account) before it works — an unclaimed server returns "not authorized for the account" even when you're signed in. Plex normally claims on first
localhostsign-in, which isn't reachable through the reverse proxy, so claiming is done with a claim token (Link Plex Account). - Hardware transcoding requires Plex Pass and the variant matching your GPU. Software transcoding works without Plex Pass.
- Plex apps cannot use the Tor address. Remote access for Plex apps relies on Plex's own Remote Access/relay (configured in Plex after linking); the Tor and
.localURLs are for the web interface.
The Plex Media Server binary and the plexinc/pms-docker image run unmodified. The package adds StartOS integration (interfaces, actions, tasks, backups, media-source mounts) and manages a small set of Preferences.xml attributes.
See CONTRIBUTING.md for build instructions and development workflow.
package_id: plex
image: plexinc/pms-docker
architectures: [x86_64, aarch64]
variants: [generic, nvidia, intel, amd]
hardware_acceleration: true
volumes:
config: /config
transcode: /transcode
startos: internal
media_mounts:
filebrowser: /data/filebrowser
nextcloud: /data/nextcloud
ports:
ui: 32400 # path /web
startos_managed_env_vars:
PLEX_CLAIM: set while a claim token is stored and the server is unlinked
managed_preferences:
- FriendlyName
actions:
- link-account
- media-sources
- server-name
account_required: true # web app always signs in to plex.tv; no account-free mode
claim_required: true # server must be claimed to an account via PLEX_CLAIM; unclaimed returns "not authorized for the account"
dependencies:
filebrowser: { optional: true, kind: exists }
nextcloud: { optional: true, kind: exists }