# Magent

Magent is a self-hosted home for media requests, viewing insights and issue
follow-up. It sits in front of Jellyfin, Seerr, Sonarr, Radarr and related apps,
then turns their technical state into a clearer experience for the people using
your server.

**Public preview:** `0.1.0-preview.1` · [Source code](https://git.amslabs.net/Rephl3x/Magent-Public) ·
[Docker Hub](https://hub.docker.com/r/rephl3xnz/magent) · [MIT license](LICENSE)

![Magent's first-run setup wizard](docs/images/setup-wizard.webp)

Magent does not store or stream media, replace your existing applications, or
provide content. You bring and operate those services; Magent connects to them.

## Why Magent?

Media automation is powerful, but its status messages are written for operators.
Magent gives users one place to request something, understand what is happening,
see when it is ready, report a problem and follow the response.

- Search for and submit movie or TV requests through Seerr.
- Follow a request across approval, Arr monitoring, download and Jellyfin availability.
- Open ready titles in Jellyfin and report playback or library problems.
- View private Jellystat-powered viewing insights and monthly reports.
- Offer local or Jellyfin sign-in, invite-only registration and per-user features.
- Manage integrations, users, branding, notifications and diagnostics from the UI.
- Export an encrypted backup of configuration, SQLite data and optional artwork.

## Current scope

- The published container is validated on **Linux/amd64**.
- Magent is a single-instance application using one writable SQLite database. It
  is not an HA, Kubernetes or multi-replica deployment.
- Native Windows foreground operation has been smoke-tested. Linux systemd files
  are statically validated; macOS instructions are reviewed but not runtime-tested.
- This is an early public release. Pin an immutable image tag or digest, retain
  backups, and test upgrades before using them on your main instance.

See [release notes](CHANGELOG.md) and [installation support boundaries](docs/INSTALLATION.md#platform-and-support-boundaries).

## Quick start with Docker Compose

Docker Compose is the recommended first installation. Create an empty directory,
download the public Compose file, and start Magent:

```sh
curl --fail --location --output compose.yml \
  https://git.amslabs.net/Rephl3x/Magent-Public/raw/branch/release/compose.yml
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 exec --user magent magent \
  python -m app.container_bootstrap setup-token
```

PowerShell:

```powershell
Invoke-WebRequest -Uri 'https://git.amslabs.net/Rephl3x/Magent-Public/raw/branch/release/compose.yml' -OutFile compose.yml
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 exec --user magent magent python -m app.container_bootstrap setup-token
```

Open `http://SERVER_IP:3000/setup`, enter the console-only token and confirm the
browser-facing URL. Then create the first administrator and connect the apps you
use. Optional integrations can be skipped. The managed image creates and retains
its own private keys; this path needs no `.env` or Dockerfile.

If you cloned the repository, the optional helper exposes the same operations:
`./setup.sh check`, `./setup.sh install`, and `./setup.sh token`. Read a script
before running it; the documented Compose commands remain the canonical path.

For public access, configure DNS and HTTPS before creating the administrator.
Do not forward the plain HTTP port directly to the internet.

## Other installation methods

| Method | Guide |
| --- | --- |
| Docker Compose | [Complete Docker guide](docs/DOCKER.md#docker-compose) |
| Docker CLI without Compose | [`docker run` guide](docs/DOCKER.md#docker-cli-without-compose) |
| Portainer | [Paste-and-deploy stack](docs/PORTAINER.md) |
| Build the container from source | [Source-build override](docs/DOCKER.md#build-the-container-from-source) |
| Native Linux | [Python/Node and systemd](docs/NATIVE_INSTALL.md) |
| Windows, macOS or Linux foreground | [Local/source installation](docs/LOCAL_DEVELOPMENT.md) |

Start with the [installation overview](docs/INSTALLATION.md) if you are unsure.
The [environment reference](docs/ENVIRONMENT.md) documents every supported
variable, while [backup and recovery](docs/installation-and-recovery.md) covers
portable exports, offline snapshots and safe restore.

### Existing installations

Keep the same Compose project name, data mount and signing/encryption keys. The
fresh-install named volume is not an automatic migration of an existing bind
mount. Record your working image digest and make an encrypted backup before an
upgrade. Never use `docker compose down -v` on data you want to keep.

## Build and test from source

```sh
git clone --branch release --single-branch https://git.amslabs.net/Rephl3x/Magent-Public.git
cd Magent-Public
docker compose -f compose.yml -f compose.build.yml -p magent up -d --build
```

The full quality gate uses Python 3.14 and Node.js 24:

```sh
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
npm run build
```

On Windows, use `.venv\Scripts\Activate.ps1`. Tests must use synthetic data and
must never point at live media services.

## Project layout

- `backend/app/`: FastAPI routes, service clients, request state, authentication,
  setup, notifications and encrypted backups.
- `frontend/app/`: Next.js pages, shared UI, account portal and administration.
- `backend/tests/` and frontend `*.test.*`: synthetic regression tests.
- `compose.yml`: prebuilt-image install; `compose.build.yml`: source-build override.
- `deploy/native/`: example Linux service units and private configuration templates.
- `docs/`: installation, environment, HTTPS, backup, upgrade and rollback guidance.

The `release` branch is a deliberately small public export. It excludes private
deployment automation, credentials, runtime data and internal Git history.

## Help, feedback and contributions

- Read [SUPPORT.md](SUPPORT.md) before opening an installation or bug report.
- See [CONTRIBUTING.md](CONTRIBUTING.md) for development and pull-request checks.
- Report security concerns using [SECURITY.md](SECURITY.md); never post secrets or
  exploit details in a public issue.
- Community participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

Magent was developed through an iterative, AI-assisted workflow and then checked
with automated regression tests, isolated container smoke tests and a sanitized
public-release pass. Treat generated code like any other code: inspect it, test
it and report anything that does not make sense.

Magent is licensed under the [MIT License](LICENSE). Dependencies and base-image
components retain their own licenses; see [third-party notices](THIRD_PARTY_NOTICES.md).