Guardian

Guardian is a security and management platform for Plex Media Server. Monitor streaming activity, enforce granular access controls, and ensure only authorized devices can access your media library.

---

Table of Contents

• Features
• Screenshots
• Installation
• Docker (Recommended)
• Proxmox
• Unraid
• Configuration
• Updating
• Application Settings
• Troubleshooting
• Password Recovery
• Common Issues
• Viewing Logs
• Getting Help
• Contributing

---

Features

Device Security & Access Control

• Automatic Session Termination - Block unapproved devices instantly
• Flexible Access Rules - Global and per-user blocking configurations
• IP-Based Controls - Restrict access by LAN, WAN, or specific IP/CIDR ranges
• Temporary Access - Grant time-limited device permissions
• Schedule-Based Restrictions - Define custom access schedules per user

Real-time Monitoring & Tracking

• Live Session Tracking - Monitor Plex and Plexamp streams in real-time
• Detailed Device Information - Platform, product, version, IP address, and last seen
• Stream Analytics - Track title, quality, duration, and progress
• Session History - Logging with filtering and search

Notifications & Alerts

• SMTP Email Integration - Real-time notifications for security events
• Apprise Support - Send alerts to 100+ services (Discord, Slack, Telegram, etc.)
• Customizable Triggers - Configure alerts for new devices, blocks, and more
• Secure Delivery - TLS/STARTTLS encryption and authentication support

User Interface & Experience

• Customizable Messages - Tailor blocking messages for different scenarios
• Rich Media Display - Thumbnails and background artwork for active streams
• Theme Support - Modern dark/light mode
• Responsive Design - Optimized for mobile and desktop
• Custom Plex Integration - Seamless content access with custom URLs

Configuration & Management

• Adjustable Monitoring - Configure refresh intervals to suit your needs
• SSL/TLS Support - Secure connections with certificate validation controls
• Database Management - Export and import for backup and migration
• Automatic Cleanup - Remove inactive devices based on inactivity periods
• Administrative Tools - Database management from the UI
• Update Management - Automatic update checking with version mismatch detection

---

Screenshots

Installation

Docker (Recommended)

Prerequisites

• Docker and Docker Compose installed
• Plex Media Server running and accessible
• Plex authentication token (How to find your token)

Quick Start

# Create a directory for Guardian
mkdir -p guardian && cd guardian

# Download configuration files
curl -o docker-compose.yml https://raw.githubusercontent.com/HydroshieldMKII/Guardian/main/docker-compose.example.yml
curl -o .env https://raw.githubusercontent.com/HydroshieldMKII/Guardian/main/.env.example

# Start Guardian
docker compose up -d

Access Guardian

• Local: http://localhost:3000
• Remote: http://YOUR-SERVER-IP:3000

Build from Source

# Clone the repository
git clone https://github.com/HydroshieldMKII/Guardian.git
cd Guardian

# Start Guardian with build
docker compose -f docker-compose.dev.yml up -d --build

---

Proxmox

Deploy Guardian in a lightweight LXC container using the community script.

Prerequisites

• Proxmox VE server
• Plex Media Server running and accessible
• Plex authentication token

Installation

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/guardian.sh)"

Follow the interactive prompts, then access Guardian at http://[CONTAINER-IP]:3000.

[!NOTE] For detailed Proxmox configuration options, see the community script documentation.

---

Unraid

Prerequisites

• Unraid server
• Compose Manager plugin installed

Installation Steps

1. Navigate to Docker → Compose
2. Create a new stack
3. Paste the contents of docker-compose.example.yml
4. Customize volumes and ports (optional):

```yaml volumes: - /mnt/user/appdata/guardian:/app/data

ports: - "3456:3000" ```

1. Deploy with Compose Up
2. Access at http://[UNRAID-IP]:3456

---

Configuration

Guardian can be configured through environment variables or the web interface.

Environment Variables

Create a .env file to customize deployment settings:

Variable	Description	Default	Applies To
PLEXGUARD_FRONTEND_PORT	Web interface port	3000	Docker, Proxmox, Unraid
VERSION	Docker image version	latest	Docker, Unraid

Example .env file:

PLEXGUARD_FRONTEND_PORT=3456
VERSION=v1.2.3

File Locations

• Docker: Place .env in the same directory as docker-compose.yml
• Proxmox: Place .env at /opt/guardian/.env inside the LXC

Applying Changes

Docker:

docker compose up -d --force-recreate

Proxmox:

systemctl restart guardian-backend guardian-frontend

[!IMPORTANT] Most configuration is done through Guardian's web interface. Environment variables are primarily for deployment customization.

---

Updating

[!IMPORTANT] Always backup your database before updating (Settings → Admin Tools → Export Database).

Docker

Manual Update:

docker compose pull
docker compose up -d

Automated Updates with Watchtower:

Guardian works seamlessly with Watchtower for automatic updates.

Proxmox

Update from the LXC console:

# Method 1
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/guardian.sh)" -u

# Method 2
update

---

Application Settings

Configure Guardian through the web interface Settings page.

Plex Integration

Connect Guardian to your Plex Media Server to enable session monitoring and device management.

Setting	Description	Default
Plex Server IP	The IP address or hostname where your Plex Media Server is running (e.g., 192.168.1.100 or plex.local)	-
Plex Server Port	The port number your Plex server listens on for API requests	32400
Plex Authentication Token	Your Plex authentication token required for Guardian to communicate with your server (How to find your token)	-
Use SSL/HTTPS	Connect to your Plex server using encrypted HTTPS instead of unencrypted HTTP	Disabled
Ignore SSL Certificate Errors	Skip SSL certificate validation when connecting to Plex (useful for self-signed certificates, but not recommended for production environments)	Disabled
Custom Plex URL	Override the default Plex URL used when opening media links (e.g., https://app.plex.tv or your custom domain)	-

Guardian Configuration

Core security behavior, monitoring settings, and access control options.

Setting	Description	Default
Auto-Check Updates	Automatically check for new Guardian releases when the application starts and notify you of available updates	Enabled
Block New Devices	Automatically block streaming access for all newly detected devices until they are manually approved by an administrator	Enabled
Strict Mode	Automatically approve or reject new devices based on the default blocking policy. Existing pending devices will also be affected by this setting	Disabled
Session Refresh Interval	How frequently Guardian checks for active Plex sessions and enforces access rules (in seconds). Lower values provide faster response but increase server load. It have no effect on the dashboard refresh rate.	10
Global Concurrent Stream Limit	Maximum number of simultaneous streams allowed per user across all their devices (set to 0 for unlimited streams). Make sure that plex is set to unlimited in its own settings to avoid conflicts.	0
Include Temp Access in Limit	When enabled, devices with temporary access are counted towards the user's concurrent stream limit	Disabled
Auto Device Cleanup	Automatically remove devices that haven't been seen for a specified period to keep your device list clean	Disabled
Cleanup Threshold (Days)	Number of days of inactivity before a device is automatically removed when auto cleanup is enabled	30
Timezone	UTC offset used for time-based access restrictions and scheduling (e.g., +00:00, -05:00, +05:30)	+00:00

User Portal Settings

Configure the self-service portal that allows Plex users to view and manage their own devices.

Setting	Description	Default
Enable User Portal	Allow Plex users to log in with their Plex credentials and view their registered devices. When disabled, Plex login only works for admin-linked accounts	Enabled
Show Rules in Portal	Allow Plex users to see the access rules assigned to them, including network policies, concurrent stream limits, and time-based restrictions	Enabled
Allow Notes on Rejected Devices	Allow Plex users to submit notes or access requests for devices that have been rejected, which administrators can review	Enabled

Customization

Personalize the user interface and customize messages shown to users.

| Setting | Description