Magent

Magent is a friendly, AI-assisted request tracker for Seerr + 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

1. Requests are pulled from Seerr and stored locally.
2. Magent joins that request to Sonarr/Radarr, Prowlarr, qBittorrent, and Jellyfin using TMDB/TVDB IDs and download hashes.
3. A state engine normalizes noisy service statuses into a simple, user-friendly state.
4. The UI renders a timeline and a central status box for each request.
5. 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 Seerr, 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

1. Create .env with your service URLs and API keys.
2. Run docker compose up --build.
3. Log in at http://localhost:3000.
4. 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="replace-with-a-long-random-secret"
JWT_EXP_MINUTES="720"
ADMIN_USERNAME="set-a-real-admin-username"
ADMIN_PASSWORD="set-a-long-unique-admin-password"

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="replace-with-a-long-random-secret"
$env:JWT_EXP_MINUTES="720"
$env:ADMIN_USERNAME="set-a-real-admin-username"
$env:ADMIN_PASSWORD="set-a-long-unique-admin-password"

Frontend (Next.js)

cd frontend
npm install
npm run dev

Open http://localhost:3000

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

Login uses the admin credentials above (or any other local user you create in SQLite).

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.

Gitea CI/CD

This repo now includes a Gitea Actions workflow at .gitea/workflows/ci-cd.yml.

• Push to beta: runs the backend unit-test quality gate and a production frontend build.
• Push to prod: runs the same verification, then deploys to Docker on AMS-DEV01.

The deploy step ships tracked repository files over SSH, preserves the server's .env and data/, rebuilds with docker compose up -d --build, and smoke-tests:

• http://127.0.0.1:8000/health
• http://127.0.0.1:3000/login

Configure these Gitea Actions secrets before enabling the deploy job:

• PROD_SSH_PRIVATE_KEY: private key for the deployment account.
• PROD_SSH_HOST: target host, for example AMS-DEV01.
• PROD_SSH_USER: target user, for example zak.
• PROD_DEPLOY_PATH: target app path, for example /home/zak/magent.
• PROD_SSH_KNOWN_HOSTS: optional pinned known_hosts entry for stricter host verification.

History endpoints

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

Troubleshooting

Login fails

• 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 Seerr 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.