SkillAgentSearch skills...

Guardian

Guardian is a lightweight companion app for Plex that lets you monitor, approve or block devices in real time. It helps you enforce per-user or global policies, stop unwanted sessions automatically and grant temporary access - all through a simple web interface.

GenerateConvertImprove

Install / Use

/learn @HydroshieldMKII/Guardian
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

Guardian

Build Docker Pulls Stars Discord

Guardian Banner

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.

[!WARNING] Project status - Looking for a Maintainer

This project is feature-complete from the author's perspective. No new features will be added unless a suitable maintainer or volunteer steps up to take the lead. Security patches may be slow to arrive in the meantime.

Do not expose Guardian to the public internet without proper protection. Safe options include:

  • Running it on your local network only
  • Accessing it through a VPN
  • Placing it behind a reverse proxy with SSO or authentication (e.g., Authelia, Authentik, Cloudflare Access)

If you're interested in becoming a maintainer (managing PRs, issues, and pipelines), please reach out via Discord or the GitHub Discussions.

Table of Contents

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

<img width="3024" alt="Guardian Dashboard - Device Management" src="https://github.com/user-attachments/assets/d0283784-c009-467e-8e38-b0d7f3907ba0" /> <img width="3024" alt="Guardian Dashboard - Active Streams" src="https://github.com/user-attachments/assets/3c2e9d9b-0836-4e95-913d-fcc71634820f" />

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

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

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

ports:
  - "3456:3000"

  5. Deploy with Compose Up

  6. 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 |

HydroshieldMKII

View profile

View on GitHub
GitHub Stars167
CategoryDevelopment
Updated1d ago
Forks3
HydroshieldMKII/Guardian

Languages

TypeScript

Security Score

85/100

Audited on Mar 27, 2026

No findings