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 in one non-root container.

Install

Paste compose.yml into a Portainer Docker Standalone stack. It uses rephl3xnz/magent:latest, persists data in a named volume and needs no environment variables or Dockerfile on the user's machine.

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. Deploy the stack and wait for the container to become healthy.

2. In its console, select /bin/ash and user magent, then run:

   python -m app.container_bootstrap setup-token
   

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

4. 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 Portainer setup, 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 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.

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.