Magent/README.md

Magent

Self-hosted media requests, viewing stats and issue management for Jellyfin, Seerr, Sonarr, Radarr and related services. Magent combines a Python/FastAPI API, a Next.js frontend and SQLite. Run the prebuilt non-root container or install the Python and Node.js services directly—Portainer is optional.

Install

Start with the installation guide to choose a method:

Method	Instructions
Docker Compose or docker run	Docker installation
Portainer	Single-file stack
Linux without Docker	Native install and systemd services
Windows/macOS/Linux foreground	Source installation and development

For a fresh Docker Compose install, download compose.yml into its own deployment directory and run:

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 ps
docker compose -f compose.yml -p magent exec --user magent magent python -m app.container_bootstrap setup-token

Keep that directory/project name and its persistent volume unchanged for updates. This uses rephl3xnz/magent:latest with no environment variables, local source build or Dockerfile. Portainer users can paste the same file into a Docker Standalone stack instead. Native users follow their separate guide for explicit environment configuration and service management.

Image availability: the managed-install image is published on Docker Hub. Only Linux/amd64 has been validated. latest is mutable; record the resolved image digest before updating, or pin an immutable release tag.

1. Wait for the container to become healthy and retrieve the token using the command above (or the Portainer console instructions in its guide).
2. Open the Docker host's address on port 3000. Confirm the browser-facing URL in setup and use the token to create the first administrator. The Get setup token button shows the console instructions and lets you copy the command; it never reveals the token to public visitors.
3. Connect your apps, choose preferences and finish setup. Optional apps can be skipped. Save an encrypted backup afterwards.

Keep the Compose security block unchanged. Database storage is fixed at /app/data/magent.db and API docs are disabled in managed installs. CORS and cookie security follow the confirmed URL. Use HTTPS before public access.

See all installation methods, all environment options, backup and restore and advanced installation/upgrades. Existing installations must retain their original data volume and signing/ encryption keys; this fresh-install template is not an automatic migration.

Build and test

The source tree contains everything needed to build the application:

docker compose -f compose.yml -f compose.build.yml -p magent up -d --build

For a disposable verification run, without touching an existing installation:

docker build -t magent:review .
bash scripts/ci_container_smoke.sh magent:review
MAGENT_SMOKE_MANAGED=true bash scripts/ci_container_smoke.sh magent:review

Unit checks require Python 3.14 and Node 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

On Windows, activate .venv\Scripts\Activate.ps1 instead. Do not point tests at live services or use production credentials.

How it is organised

• backend/app/routers/: authenticated API endpoints and administration.
• backend/app/clients/: media-service clients; services/: request states, synchronisation, notifications, setup and encrypted backups.
• backend/app/db.py and schema_migrations.py: SQLite persistence/migrations.
• frontend/app/: pages and shared interface components; frontend/proxy.ts: browser security headers and request nonces.
• backend/tests/ and frontend *.test.*: synthetic regression tests.
• Dockerfile and docker/: multi-stage build and process supervision.
• compose.yml: prebuilt-image install; compose.build.yml: source override.
• deploy/native/: example Linux service units and backend/frontend configuration.

Requests are cached from Seerr, joined to collector/download/library evidence, normalised into a user-facing state and displayed by the frontend. App settings are stored in SQLite; sensitive settings are encrypted with installation-specific keys. Integrations are optional and are configured through the setup wizard.

This release branch intentionally excludes internal deployment scripts, environment files, runtime data, development reports and prior Git history. It contains no workflow that automatically deploys or publishes an image.

Contributing and security

Keep changes focused, add regression tests and run the checks above. Never commit tokens, database exports, backups or real user information. See SECURITY.md for reporting guidance and deployment precautions.

Licensed under MIT. Third-party dependency licences remain applicable.