Magent-Public/README.md

Magent

Magent is a self-hosted home for media requests, viewing insights and issue follow-up. It sits in front of Jellyfin, Seerr, Sonarr, Radarr and related apps, then turns their technical state into a clearer experience for the people using your server.

Public preview: 0.1.0-preview.1 · Source code · Docker Hub · MIT license

Magent does not store or stream media, replace your existing applications, or provide content. You bring and operate those services; Magent connects to them.

Why Magent?

Media automation is powerful, but its status messages are written for operators. Magent gives users one place to request something, understand what is happening, see when it is ready, report a problem and follow the response.

• Search for and submit movie or TV requests through Seerr.
• Follow a request across approval, Arr monitoring, download and Jellyfin availability.
• Open ready titles in Jellyfin and report playback or library problems.
• View private Jellystat-powered viewing insights and monthly reports.
• Offer local or Jellyfin sign-in, invite-only registration and per-user features.
• Manage integrations, users, branding, notifications and diagnostics from the UI.
• Export an encrypted backup of configuration, SQLite data and optional artwork.

Current scope

• The published container is validated on Linux/amd64.
• Magent is a single-instance application using one writable SQLite database. It is not an HA, Kubernetes or multi-replica deployment.
• Native Windows foreground operation has been smoke-tested. Linux systemd files are statically validated; macOS instructions are reviewed but not runtime-tested.
• This is an early public release. Pin an immutable image tag or digest, retain backups, and test upgrades before using them on your main instance.

See release notes and installation support boundaries.

Quick start with Docker Compose

Docker Compose is the recommended first installation. Create an empty directory, download the public Compose file, and start Magent:

curl --fail --location --output compose.yml \
  https://git.amslabs.net/Rephl3x/Magent-Public/raw/branch/release/compose.yml
docker compose -f compose.yml -p magent pull
docker compose -f compose.yml -p magent up -d --wait --wait-timeout 120
docker compose -f compose.yml -p magent exec --user magent magent \
  python -m app.container_bootstrap setup-token

PowerShell:

Invoke-WebRequest -Uri 'https://git.amslabs.net/Rephl3x/Magent-Public/raw/branch/release/compose.yml' -OutFile compose.yml
docker compose -f compose.yml -p magent pull
docker compose -f compose.yml -p magent up -d --wait --wait-timeout 120
docker compose -f compose.yml -p magent exec --user magent magent python -m app.container_bootstrap setup-token

Open http://SERVER_IP:3000/setup, enter the console-only token and confirm the browser-facing URL. Then create the first administrator and connect the apps you use. Optional integrations can be skipped. The managed image creates and retains its own private keys; this path needs no .env or Dockerfile.

If you cloned the repository, the optional helper exposes the same operations: ./setup.sh check, ./setup.sh install, and ./setup.sh token. Read a script before running it; the documented Compose commands remain the canonical path.

For public access, configure DNS and HTTPS before creating the administrator. Do not forward the plain HTTP port directly to the internet.

Other installation methods

Method	Guide
Docker Compose	Complete Docker guide
Docker CLI without Compose	docker run guide
Portainer	Paste-and-deploy stack
Build the container from source	Source-build override
Native Linux	Python/Node and systemd
Windows, macOS or Linux foreground	Local/source installation

Start with the installation overview if you are unsure. The environment reference documents every supported variable, while backup and recovery covers portable exports, offline snapshots and safe restore.

Existing installations

Keep the same Compose project name, data mount and signing/encryption keys. The fresh-install named volume is not an automatic migration of an existing bind mount. Record your working image digest and make an encrypted backup before an upgrade. Never use docker compose down -v on data you want to keep.

Build and test from source

git clone --branch release --single-branch https://git.amslabs.net/Rephl3x/Magent-Public.git
cd Magent-Public
docker compose -f compose.yml -f compose.build.yml -p magent up -d --build

The full quality gate uses Python 3.14 and Node.js 24:

python -m venv .venv
. .venv/bin/activate
pip install -r backend/requirements-dev.txt
python -m unittest discover -s backend/tests -p 'test_*.py'
python scripts/check_environment_docs.py
cd frontend
npm ci
npm test
npm run lint
npm run format:check
npm run typecheck
npm run build

On Windows, use .venv\Scripts\Activate.ps1. Tests must use synthetic data and must never point at live media services.

Project layout

• backend/app/: FastAPI routes, service clients, request state, authentication, setup, notifications and encrypted backups.
• frontend/app/: Next.js pages, shared UI, account portal and administration.
• backend/tests/ and frontend *.test.*: synthetic regression tests.
• compose.yml: prebuilt-image install; compose.build.yml: source-build override.
• deploy/native/: example Linux service units and private configuration templates.
• docs/: installation, environment, HTTPS, backup, upgrade and rollback guidance.

The release branch is a deliberately small public export. It excludes private deployment automation, credentials, runtime data and internal Git history.

Help, feedback and contributions

• Read SUPPORT.md before opening an installation or bug report.
• See CONTRIBUTING.md for development and pull-request checks.
• Report security concerns using SECURITY.md; never post secrets or exploit details in a public issue.
• Community participation follows CODE_OF_CONDUCT.md.

Magent was developed through an iterative, AI-assisted workflow and then checked with automated regression tests, isolated container smoke tests and a sanitized public-release pass. Treat generated code like any other code: inspect it, test it and report anything that does not make sense.

Magent is licensed under the MIT License. Dependencies and base-image components retain their own licenses; see third-party notices.