Know who's streaming. Catch account sharers. Take back control.
---
Tracearr is a streaming access manager for **Plex**, **Jellyfin**, and **Emby** that answers one question: *Who's actually using my server, and are they sharing their login?*
Unlike monitoring tools that just show you data, Tracearr is built to detect account abuse. See streams in real-time, flag suspicious activity automatically, and get notified the moment something looks off.
## What It Does
**Session Tracking** β Full history of who watched what, when, from where, on what device. Every stream logged with geolocation data.
**Sharing Detection** β Five rule types catch account sharers:
- π **Impossible Travel** β NYC then London 30 minutes later? That's not one person.
- π **Simultaneous Locations** β Same account streaming from two cities at once.
- π **Device Velocity** β Too many unique IPs in a short window signals shared credentials.
- πΊ **Concurrent Streams** β Set limits per user. Simple but effective.
- π **Geo Restrictions** β Block streaming from specific countries entirely.
**Real-Time Alerts** β Discord webhooks and custom notifications fire instantly when rules trigger. No waiting for daily reports.
**Stream Map** β Visualize where your streams originate on an interactive world map. Filter by user, server, or time period to zero in on suspicious patterns.
**Trust Scores** β Users earn (or lose) trust based on their behavior. Violations drop scores automatically.
**Multi-Server** β Connect Plex, Jellyfin, and Emby instances to the same dashboard. Manage everything in one place.
**Tautulli Import** β Already using Tautulli? Import your watch history so you don't start from scratch.
## What It Doesn't Do (Yet)
Tracearr v1 is focused on **detection and alerting**. Automated enforcementβkilling streams, suspending accountsβis coming in future versions. For now, you see the problems; you decide the action.
## Why Not Tautulli or Jellystat?
[Tautulli](https://github.com/Tautulli/Tautulli) and [Jellystat](https://github.com/CyferShepard/Jellystat) are great monitoring tools. We use Highcharts for graphs too. But they show you what happenedβthey don't tell you when something's wrong.
| | Tautulli | Jellystat | Tracearr |
|---|---|---|---|
| Watch history | β
| β
| β
|
| Statistics & graphs | β
| β
| β
|
| Session monitoring | β
| β
| β
|
| Account sharing detection | β | β | β
|
| Impossible travel alerts | β | β | β
|
| Trust scoring | β | β | β
|
| Plex support | β
| β | β
|
| Jellyfin support | β | β
| β
|
| Emby support | β | β
| β
|
| Multi-server dashboard | β | β | β
|
| IP geolocation | β
| β
| β
|
| Import from Tautulli | β | β | β
|
Tautulli and Jellystat are platform-locked equivalentsβPlex-only vs Jellyfin/Emby-only. If you just want stats, they work fine. If you're tired of your brother's roommate's cousin streaming on your dime, that's what Tracearr is for.
## Quick Start
### Option 1: All-in-One (Recommended)
The supervised image bundles TimescaleDB, Redis, and Tracearr in a single container. No external database required. Secrets are auto-generated on first run.
```bash
docker compose -f docker/docker-compose.supervised.yml up -d
```
Open `http://localhost:3000` and connect your Plex, Jellyfin, or Emby server.
### Option 2: Separate Services
If you already have TimescaleDB/PostgreSQL and Redis, or prefer managing services separately:
```bash
# Copy and configure environment
cp docker/.env.example docker/.env
# Edit docker/.env with your secrets (generate with: openssl rand -hex 32)
docker compose -f docker/docker-compose.yml up -d
```
### Docker Tags
| Tag | Description |
|-----|-------------|
| `latest` | Stable release (requires external DB/Redis) |
| `supervised` | All-in-one stable release |
| `next` | Latest prerelease |
| `supervised-nightly` | All-in-one nightly build |
| `nightly` | Bleeding edge nightly |
```bash
# All-in-one (easiest)
docker pull ghcr.io/connorgallopo/tracearr:supervised
# Stable (requires external services)
docker pull ghcr.io/connorgallopo/tracearr:latest
# Living on the edge
docker pull ghcr.io/connorgallopo/tracearr:nightly
```
### Development Setup
```bash
# Install dependencies (requires pnpm 10+, Node.js 22+)
pnpm install
# Start database services
docker compose -f docker/docker-compose.dev.yml up -d
# Copy and configure environment
cp .env.example .env
# Run migrations
pnpm --filter @tracearr/server db:migrate
# Start dev servers
pnpm dev
```
Frontend runs at `localhost:5173`, API at `localhost:3000`.
## Stack
| Layer | Tech |
|---|---|
| Frontend | React 19, TypeScript, Tailwind, shadcn/ui |
| Charts | Highcharts |
| Maps | Leaflet |
| Backend | Node.js, Fastify |
| Database | TimescaleDB (PostgreSQL extension) |
| Cache | Redis |
| Real-time | Socket.io |
| Monorepo | pnpm + Turborepo |
**TimescaleDB** handles session history. Regular Postgres works fine until you have a year of watch data and your stats queries start taking forever. TimescaleDB is built for exactly this kind of time-series dataβdashboard stats stay fast because they're pre-computed, not recalculated every page load.
**Fastify** over Express because it's measurably faster and the schema validation is nice.
**Plex SSE** β Plex servers stream session updates in real-time via Server-Sent Events. No polling delay, instant detection. Jellyfin and Emby still use polling (they don't support SSE), but Plex sessions appear the moment they start.
## Project Structure
```
tracearr/
βββ apps/
β βββ web/ # React frontend
β βββ server/ # Fastify backend
β βββ mobile/ # React Native app (coming soon)
βββ packages/
β βββ shared/ # Types, schemas, constants
βββ docker/ # Compose files
βββ docs/ # Documentation
```
## Configuration
Tracearr uses environment variables for configuration. Key settings:
```bash
# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/tracearr
# Redis
REDIS_URL=redis://localhost:6379
# Security
JWT_SECRET=your-secret-here
COOKIE_SECRET=your-cookie-secret-here
# GeoIP (optional, for location detection)
MAXMIND_LICENSE_KEY=your-maxmind-key
```
See `.env.example` for all options.
## Community
Got questions? Found a bug? Want to contribute?
[](https://discord.gg/a7n3sFd2Yw)
Or [open an issue](https://github.com/connorgallopo/Tracearr/issues) on GitHub.
## Contributing
Contributions welcome. Please:
1. Fork the repo
2. Create a feature branch (`git checkout -b feature/thing`)
3. Make your changes
4. Run tests and linting (`pnpm test && pnpm lint`)
5. Open a PR
Check the [issues](https://github.com/connorgallopo/Tracearr/issues) for things to work on.
## Roadmap
**Alpha** (current β v0.1.x)
- [x] Multi-server Plex, Jellyfin, and Emby support
- [x] Session tracking with full history
- [x] 5 sharing detection rules
- [x] Real-time WebSocket updates
- [x] Plex SSE for instant session detection
- [x] Discord + webhook notifications
- [x] Interactive stream map
- [x] Trust scores
- [x] Tautulli history import
**v1.5** (next milestone)
- [ ] Mobile app (iOS & Android) β *in development*
- [ ] Stream termination (kill suspicious streams)
- [ ] Account suspension automation
- [ ] Email notifications
- [ ] Telegram notifier
**v2.0** (future)
- [ ] Tiered access controls
- [ ] Arr integration (Radarr/Sonarr)
- [ ] Multi-admin support
## License
[AGPL-3.0](LICENSE) β Open source with copyleft protection. If you modify Tracearr and offer it as a service, you share your changes.
---
Built because sharing is caring, but not when it's your server bill.