99 lines
3.0 KiB
Markdown
99 lines
3.0 KiB
Markdown
# Magent
|
|
|
|
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
|
|
|
|
1) Requests are pulled from Jellyseerr 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 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.
|
|
|
|
## Backend (FastAPI)
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
$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)
|
|
|
|
```bash
|
|
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).
|
|
|
|
## Docker (Testing)
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
Backend: http://localhost:8000
|
|
Frontend: http://localhost:3000
|
|
|
|
## 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
|