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.

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

• 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

• 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

• 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

• 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

• 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

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

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.

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):

   volumes:
     - /mnt/user/appdata/guardian:/app/data
   
   ports:
     - "3456:3000"

5. Deploy with Compose Up

6. Access at http://[UNRAID-IP]:3456

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

Create a .env file to customize deployment settings:

Example .env file:

PLEXGUARD_FRONTEND_PORT=3456
VERSION=v1.2.3

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

Docker:

docker compose up -d --force-recreate

Proxmox:

systemctl restart guardian-backend guardian-frontend

Manual Update:

docker compose pull
docker compose up -d

Automated Updates with Watchtower:

Guardian works seamlessly with Watchtower for automatic updates.

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

Configure Guardian through the web interface Settings page.

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

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

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

Personalize the user interface and customize messages shown to users.

Customize the messages displayed to users when their streaming access is blocked for various reasons:

Configure how Guardian delivers notifications about security events and device activity.

Send email alerts for important Guardian events using your SMTP server.

Send notifications to 100+ services including Discord, Slack, Telegram, Pushover, and many more using the Apprise notification library.

Backup and restore your Guardian configuration, devices, and settings.

If you've lost access to your admin account, you can reset credentials from the command line.

All commands are run next to the docker-compose.yml file.

List all admin users:

docker compose exec backend node src/scripts/list-admins.js

Reset admin password:

docker compose exec backend node src/scripts/update-admin.js "USERNAME_HERE" "NEW_PASSWORD_HERE"

Replace USERNAME_HERE with your admin username and NEW_PASSWORD_HERE with your desired password.

All commands are run from inside the LXC container.

List all admin users:

node /opt/guardian/backend/src/scripts/list-admins.js

Reset admin password:

node /opt/guardian/backend/src/scripts/update-admin.js "USERNAME_HERE" "NEW_PASSWORD_HERE"

Replace USERNAME_HERE with your admin username and NEW_PASSWORD_HERE with your desired password.

If you are locked out due to captcha issues, you can disable Cloudflare Turnstile captcha via the command line. Running the command will immediately disable captcha by clearing the Turnstile site and secret keys.

All commands are run next to the docker-compose.yml file.

docker compose exec backend node src/scripts/disable-captcha.js

All commands are run from inside the LXC container.

node /opt/guardian/backend/src/scripts/disable-captcha.js

Cannot connect to Plex

• Verify Plex is running and accessible
• Confirm Plex token is valid
• Check firewall rules

Device not showing up

• Ensure refresh interval is appropriate
• Check Plex server connection
• Verify device has attempted to stream

Notifications not working

• Test connection in Settings
• Verify SMTP/Apprise credentials
• Check email spam folder

Docker:

docker compose ps
docker compose logs -f backend
docker compose logs -f frontend

Proxmox:

systemctl status guardian-backend
systemctl status guardian-frontend

# View detailed logs
journalctl -u guardian-backend -f
journalctl -u guardian-frontend -f

If issues persist:

• Join our Discord for community support
• Open an Issue with detailed information

We welcome contributions! Here's how you can help:

• Report Bugs - Open an issue with details and reproduction steps
• Suggest Features - Share your ideas in Discussions
• Improve Documentation - Submit PRs for README or docs improvements
• Submit Code - Fork, make changes, and submit a pull request