Magent is a friendly, AI-assisted request tracker for Jellyseerr + Arr services. It shows a clear timeline of where a request is stuck, explains what is happening in plain English, and offers safe actions to help fix issues.

How it works

Requests are pulled from Jellyseerr and stored locally.
Magent joins that request to Sonarr/Radarr, Prowlarr, qBittorrent, and Jellyfin using TMDB/TVDB IDs and download hashes.
A state engine normalizes noisy service statuses into a simple, user-friendly state.
The UI renders a timeline and a central status box for each request.
Optional AI triage summarizes the likely cause and safest next steps.

Core features

Request search by title/year or request ID.
Recent requests list with posters and status.
Timeline view across Jellyseerr, Arr, Prowlarr, qBittorrent, Jellyfin.
Central status box with clear reason + next steps.
Safe action buttons (search, resume, re-add, etc.).
Admin settings for service URLs, API keys, profiles, and root folders.
Health status for each service in the pipeline.
Cache and sync controls (full sync, delta sync, scheduled syncs).
Local database for speed and audit history.
Users and access control (admin vs user, block access).
Local account password changes via "My profile".
Docker-first deployment for easy hosting.

Quick start (Docker - primary)

Docker is the recommended way to run Magent. It includes the backend and frontend with sane defaults.

docker compose up --build

Then open:

Frontend: http://localhost:3000
Backend: http://localhost:8000

Docker setup steps

Create .env with your service URLs and API keys.
Run docker compose up --build.
Log in at http://localhost:3000.
Visit Settings to confirm service health.

Docker environment variables (sample)

JELLYSEERR_URL="http://localhost:5055"
JELLYSEERR_API_KEY="..."
SONARR_URL="http://localhost:8989"
SONARR_API_KEY="..."
SONARR_QUALITY_PROFILE_ID="1"
SONARR_ROOT_FOLDER="/tv"
RADARR_URL="http://localhost:7878"
RADARR_API_KEY="..."
RADARR_QUALITY_PROFILE_ID="1"
RADARR_ROOT_FOLDER="/movies"
PROWLARR_URL="http://localhost:9696"
PROWLARR_API_KEY="..."
QBIT_URL="http://localhost:8080"
QBIT_USERNAME="..."
QBIT_PASSWORD="..."
SQLITE_PATH="data/magent.db"
JWT_SECRET="change-me"
JWT_EXP_MINUTES="720"
ADMIN_USERNAME="admin"
ADMIN_PASSWORD="adminadmin"

Screenshots

Add screenshots here once available:

docs/screenshots/home.png
docs/screenshots/request-timeline.png
docs/screenshots/settings.png
docs/screenshots/profile.png

Local development (secondary)

Use this only when you need to modify code locally.

Backend (FastAPI)

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Environment variables (sample):

$env:JELLYSEERR_URL="http://localhost:5055"
$env:JELLYSEERR_API_KEY="..."
$env:SONARR_URL="http://localhost:8989"
$env:SONARR_API_KEY="..."
$env:SONARR_QUALITY_PROFILE_ID="1"
$env:SONARR_ROOT_FOLDER="/tv"
$env:RADARR_URL="http://localhost:7878"
$env:RADARR_API_KEY="..."
$env:RADARR_QUALITY_PROFILE_ID="1"
$env:RADARR_ROOT_FOLDER="/movies"
$env:PROWLARR_URL="http://localhost:9696"
$env:PROWLARR_API_KEY="..."
$env:QBIT_URL="http://localhost:8080"
$env:QBIT_USERNAME="..."
$env:QBIT_PASSWORD="..."
$env:SQLITE_PATH="data/magent.db"
$env:JWT_SECRET="change-me"
$env:JWT_EXP_MINUTES="720"
$env:ADMIN_USERNAME="admin"
$env:ADMIN_PASSWORD="adminadmin"

Frontend (Next.js)

cd frontend
npm install
npm run dev

Open http://localhost:3000

Admin panel: http://localhost:3000/admin

Public Hosting Notes

The frontend proxies /api/* to the backend container. Set:

NEXT_PUBLIC_API_BASE=/api (browser uses same-origin)
BACKEND_INTERNAL_URL=http://backend:8000 (container-to-container)

If you prefer the browser to call the backend directly, set NEXT_PUBLIC_API_BASE to your public backend URL and ensure CORS is configured.

History endpoints

GET /requests/{id}/history?limit=10 recent snapshots
GET /requests/{id}/actions?limit=10 recent action logs

Troubleshooting

Make sure ADMIN_USERNAME and ADMIN_PASSWORD are set in .env.
Confirm the backend is reachable: http://localhost:8000/health (or see container logs).

Services show as down

Check the URLs and API keys in Settings.
Verify containers can reach each service (network/DNS).

No recent requests

Confirm Jellyseerr credentials in Settings.
Run a full sync from Settings -> Requests.

Docker images not updating

Run docker compose up --build again.
If needed, run docker compose down first, then rebuild.

README.md

Magent