# SDBX complete context

> Canonical product and installation context generated from the SDBX product manifest.

## Product overview

# SDBX

> Your server. Your bandwidth. Your business. One connected system for downloading, organizing, and streaming media.

Canonical page: https://sdbx.one/

SDBX is an open-source seedbox CLI and authenticated management console for Linux boxes with suspiciously large disks. It turns explicit choices into a reproducible Docker Compose project with a verified lock file, without a hosted control plane or SDBX account.

SDBX is intended for media and sources the operator is legally permitted to access.

## Operator modes

- **Dashboard**: the remote-ready Web UI at the canonical SDBX root is protected by Authelia administrators and private Traefik mTLS. It exposes service status, bounded logs, addons, typed settings, security evidence, encrypted backups, diagnostics, audit history, and guarded stack actions. It is designed for first-time and experienced operators who prefer a polished UI after a day spent managing servers.
- **CLI advanced mode**: the complete command surface supports project initialization, generation, locks, lifecycle, registries, addons, presets, integrations, backups, diagnostics, and structured JSON output for automation.
- Both interfaces operate the same `.sdbx.yaml`, `.sdbx.lock`, generated Compose project, and local broker safeguards. The interface choice distinction is presentation and project lore, not a security boundary.

## Product workflow

1. **Discover** releases through configured indexers such as Prowlarr.
2. **Download** through qBittorrent and, when enabled, Gluetun VPN policy.
3. **Organize** libraries through automation services such as Sonarr.
4. **Watch** through Jellyfin, Plex, or both.
5. **Operate** the generated stack through the CLI or authenticated dashboard.

## Supported platforms

- linux/amd64: supported
- linux/arm64: compatibility

Release: v1.0.0-RC1 (release-candidate)
License: MIT

## Service catalog

40 services: 7 core and 33 optional addons.

### Networking
- **cloudflared** (core): Remote-managed Cloudflare Tunnel connector
- **gluetun** (core): VPN client with kill switch for Docker containers
- **traefik** (core): Modern HTTP reverse proxy and load balancer

### Auth
- **authelia** (core): Single Sign-On Multi-Factor portal

### Downloads
- **autobrr** (addon): IRC and RSS download automation for torrents and Usenet
- **cobalt** (addon): Self-hosted cobalt API backend for media-download requests
- **cross-seed** (addon): Internal cross-seeding daemon for compatible torrent trackers
- **nzbhydra2** (addon): Usenet indexer meta-search aggregator
- **pyload** (addon): Web-managed HTTP and file-hoster download client
- **qbit-manage** (addon): Scheduled qBittorrent tagging, cleanup, and data management
- **qbittorrent** (core): Free and open-source BitTorrent client
- **qui** (addon): Modern multi-instance qBittorrent Web UI and workflow engine
- **sabnzbd** (addon): Usenet binary downloader with complete and incomplete queues

### Media
- **audiobookshelf** (addon): Audiobook and podcast server with multi-user progress sync
- **bazarr** (addon): Subtitle management for movies and TV shows
- **calibre-web** (addon): Web interface for browsing, reading, and downloading a Calibre library
- **jellyfin** (core): Open-source media server (Plex alternative)
- **kometa** (addon): Scheduled Plex metadata, collection, playlist, and overlay manager
- **komga** (addon): Comic, manga, and ebook library server with OPDS support
- **lidarr** (addon): Music collection automation and management
- **navidrome** (addon): Subsonic-compatible music streaming server
- **plex** (core): Media server for streaming movies, TV, and music
- **prowlarr** (addon): Indexer manager for *arr applications
- **radarr** (addon): Movie collection automation and management
- **seerr** (addon): Media request and discovery portal for Plex and Jellyfin
- **sonarr** (addon): TV Shows automation and management
- **stash** (addon): Private media organizer with metadata, previews, and transcoding
- **tdarr** (addon): Distributed media transcoding with a safe CPU-only internal node
- **whisparr** (addon): Whisparr v3 adult-media automation and management
- **wizarr** (addon): Invitation and onboarding portal for media server users

### Management
- **tautulli** (addon): Plex activity monitoring, analytics, and notifications

### Utility
- **decluttarr** (addon): Queue cleanup automation for supported *arr applications
- **filebrowser** (addon): Web file manager for browsing, uploading, and organising seedbox files
- **flaresolverr** (addon): Internal challenge-solving proxy for compatible indexers
- **janitorr** (addon): Scheduled media lifecycle automation for *arr and media servers
- **maintainerr** (addon): Rule-based media-library lifecycle management
- **notifiarr** (addon): Notification and monitoring client for media automation services
- **profilarr** (addon): Quality profile and custom format management for Sonarr and Radarr
- **recyclarr** (addon): Scheduled quality-profile synchronization for Sonarr and Radarr
- **unpackerr** (addon): Background archive extractor for completed downloads and supported Arr services

## Selected addon behavior

- **Seerr** is the only supported request portal. SDBX does not promise an automatic migration from Overseerr.
- **Calibre-Web** preserves the selected upstream image's documented first login (`admin` / `admin123`). Change it immediately; the SDBX route adds an outer administrator boundary but does not replace the application credential.
- **pyLoad** preserves the selected upstream image's documented first login (`pyload` / `pyload`). Change it immediately.
- **Cobalt** is the official self-hosted API. Use `sdbx secrets show cobalt --confirm reveal`, then configure the endpoint and key at https://cobalt.tools/settings/instances.
- **Unpackerr** is an internal worker with no Web UI. SDBX generates its supported Arr endpoints and file-backed API-key copies.
- **Whisparr** uses the selected publisher's v3 stable line and joins the managed Arr authentication, Prowlarr, qBittorrent, and Unpackerr flows.
- **Notifiarr** keeps application notifications and service checks without Docker-socket access. **Tdarr** defaults to a portable CPU node; GPU access is not implicitly granted.

## Presets

- **TV automation (Jellyfin)**: Curated Jellyfin TV automation with Sonarr, Prowlarr for indexers, and File Browser for direct file access. Addons: filebrowser, prowlarr, sonarr.
- **TV automation (Plex)**: Curated Plex TV automation with Sonarr, Prowlarr for indexers, and File Browser for direct file access. Addons: filebrowser, prowlarr, sonarr.
- **Minimal seedbox**: Just the essentials: qBittorrent behind a VPN, plus a web file browser to poke at downloads. No automation, no media server, no requests. The smallest sane stack. Addons: filebrowser.
- **Power user**: Broad movie, TV, music, subtitle and Usenet automation with direct file access and scheduled profile synchronization. Specialist libraries, invitation portals and transcoders stay opt-in. Addons: bazarr, filebrowser, lidarr, nzbhydra2, prowlarr, radarr, recyclarr, sabnzbd, sonarr.

## Primary commands

- `sdbx init`: create a project through the guided setup.
- `sdbx lock verify`: verify the current catalog graph, locked image pins, and generated files.
- `sdbx up`: start the active locked service graph.
- `sdbx down`: stop the stack while preserving project data.
- `sdbx status`: inspect services, health, and routes.
- `sdbx doctor`: run host and stack diagnostics.
- `sdbx integrate --dry-run`: preview supported service integrations.
- `sdbx integrate`: apply supported service integrations.
- `sdbx addon list --all`: list addons across the configured service sources.
- `sdbx backup`: create an authenticated age-encrypted backup of project configuration and secrets.
- `sdbx serve`: run the brokered management console used by the generated secure route.

## Important boundaries

- **linux-host-only**: v1 first-class host support is Linux amd64; Linux arm64 is a compatibility build, and macOS is development-only.
- **docker-root-equivalent**: Docker access and the root broker are host-privileged trust boundaries.
- **authenticated-console**: The management console is public only through the generated Authelia admins route and private Traefik mTLS backend transport; direct proxy-port access fails closed.
- **optional-vpn**: VPN enforcement applies only when enabled; unprotected download traffic requires explicit confirmation.
- **remote-managed-tunnel**: A Cloudflare connector token cannot manage Published application routes; SDBX lists and probes the required remote mappings.
- **no-controller-image**: v1 publishes native binaries only; there is no supported SDBX controller container image.

## Canonical resources

- Website: https://sdbx.one/
- Installation guide for people: https://sdbx.one/install/
- Installation guide for agents: https://sdbx.one/install.md
- Product manifest: https://sdbx.one/product-manifest.json
- Source repository: https://github.com/get-sdbx/sdbx
- Source documentation: https://github.com/get-sdbx/sdbx/tree/v1.0.0-RC1/docs

## Installation guide

# Install SDBX

> Install the signed SDBX release on a supported Linux host, initialize one project, and verify the locked media stack.

Canonical human guide: https://sdbx.one/install/
Canonical release: v1.0.0-RC1

Use these instructions only after the user explicitly asks to install or configure SDBX. Preserve existing data and respect the execution environment's approval rules.

## Supported environment

- linux/amd64: supported
- linux/arm64: compatibility

Required host components:

- Docker Engine 24.0 or newer.
- Docker Compose plugin 2.20 or newer.
- Docker Buildx 0.10 or newer.
- Cosign major version 3 for signed-release verification.
- A user that can reach Docker. Docker access is root-equivalent.
- A domain controlled by the operator.
- A Gluetun-supported provider when VPN-protected torrent traffic is required.

Do not deploy SDBX as a production host on macOS, Windows, or WSL2.

## Safety contract

- Do not stop, replace, or delete an existing stack without explicit approval.
- Do not initialize inside a non-empty unrelated directory.
- Do not invent domain names, credentials, VPN providers, storage paths, or exposure policy.
- Do not print secrets or persist them in logs, chat, fixtures, or source control.
- Do not pipe a remote installer directly into a shell.
- Expose the Dashboard only through the generated Traefik route, Authelia `admins` policy, and private mTLS transport.
- Use `sdbx up`, not a raw Compose start, so lock and file integrity are checked.

## 1. Preflight

```bash
uname -s
uname -m
docker version
docker compose version
docker buildx version
cosign version
```

Continue only when the kernel reports Linux and the architecture is amd64 or arm64. Report missing prerequisites instead of bypassing them.

## 2. Download the exact signed installer

```bash
version=v1.0.0-RC1
installer="$(mktemp)"
curl --fail --show-error --location \
  --proto '=https' --proto-redir '=https' --tlsv1.2 \
  --output "$installer" \
  "https://raw.githubusercontent.com/get-sdbx/sdbx/$version/install.sh"
chmod 0600 "$installer"
```

Read the entire downloaded installer using the local file-reading tool. Confirm that it downloads the requested tag, verifies the checksum manifest with Cosign, validates archive contents, checks both embedded binary versions, and performs rollback-capable replacement.

If the installer differs from that contract, stop and report the mismatch.

## 3. Install and verify both binaries

```bash
bash "$installer" --version "$version" --install-dir "$HOME/.local/bin"
rm -f "$installer"
export PATH="$HOME/.local/bin:$PATH"
sdbx version
sdbxd -version
```

Both binaries must report v1.0.0-RC1. A partial or mismatched install is a failure.

## 4. Collect operator decisions

Before initialization, obtain explicit choices for:

- project directory;
- domain and exposure mode: LAN, direct HTTPS, or remote-managed Cloudflare Tunnel;
- subdomain or path routing;
- Plex, Jellyfin, both, or no media server;
- media, downloads, configuration, secrets, and backup paths;
- VPN enforcement, provider, and exit country;
- timezone, preset, and optional addons;
- initial administrator credential through a private input path.

Never infer these choices from the host or from unrelated files.

## 5. Initialize the project

```bash
project_dir="$HOME/sdbx-project"
mkdir -p "$project_dir"
cd "$project_dir"
sdbx init
```

The interactive wizard is the default. Do not automate password entry through command-line arguments. If non-interactive initialization is required, use the CLI's documented private password-file flow and preview it with `--dry-run` before any write.

## 6. Verify and start

```bash
sdbx lock verify
sdbx up
sdbx status
sdbx doctor
sdbx integrate --dry-run
```

Apply `sdbx integrate` only after its dry-run is reviewed.

## Success criteria

- `sdbx version` and `sdbxd -version` match the requested release.
- `.sdbx.yaml`, `.sdbx.lock`, and `compose.yaml` exist in the project directory.
- `sdbx lock verify` succeeds.
- `sdbx status` reports the intended service graph.
- `sdbx doctor` has no unresolved blocking failure.
- No secret appears in terminal capture, logs, chat, or source control.

## Recovery

- If installation fails, preserve the error and allow the installer rollback to finish.
- If initialization fails, do not manually promote staged files.
- If startup fails, run `sdbx status` and `sdbx doctor`; do not delete volumes.
- Ask before stopping another stack, changing DNS, or modifying production routing.

## More context

- LLM navigation: https://sdbx.one/llms.txt
- Full LLM context: https://sdbx.one/llms-full.txt
- Product overview: https://sdbx.one/index.md
- Product manifest: https://sdbx.one/product-manifest.json
- Source documentation: https://github.com/get-sdbx/sdbx/tree/v1.0.0-RC1/docs

## Agent installation task

# Install SDBX with an AI agent

> Task-oriented instructions for installing and verifying SDBX without guessing operator policy or bypassing release verification.

OBJECTIVE: Install the exact signed SDBX release on a supported Linux host, initialize one reviewed project, and verify the locked stack.

DONE WHEN: Both binaries match the requested version, the project lock verifies, the intended services are running, diagnostics have no unresolved blocking failure, and no secret was exposed.

Use this file only when the user explicitly requests installation. It does not grant permission to stop existing services, overwrite data, change DNS, publish an unprotected console route, or perform destructive recovery.

## Procedure

- [ ] Read the canonical installation guide at https://sdbx.one/install/index.md
- [ ] Inspect the host OS, architecture, Docker, Compose, Buildx, and Cosign versions.
- [ ] Inventory the chosen project directory and stop if unrelated files exist.
- [ ] Obtain missing domain, exposure, storage, media-server, VPN, preset, and addon decisions.
- [ ] Download the installer from the immutable v1.0.0-RC1 source tag.
- [ ] Read and verify the complete installer before execution.
- [ ] Install `sdbx` and `sdbxd` as one transaction.
- [ ] Verify both embedded versions.
- [ ] Run the interactive initialization in the approved empty project directory.
- [ ] Verify the lock, start through `sdbx up`, inspect status, and run diagnostics.
- [ ] Preview integrations and ask before applying them.
- [ ] Report the exact verification results and any remaining operator action.

## Mandatory guardrails

- Never use `curl | sh` or another remote pipe-to-shell form.
- Never fabricate credentials or pass passwords as command-line arguments.
- Never bypass the generated Authelia and mTLS management-console boundary.
- Never use raw `docker compose up` in place of `sdbx up`.
- Never delete containers, volumes, project files, or backups as troubleshooting.
- Never treat Linux arm64 compatibility as the first-class amd64 host guarantee.

## Authoritative context

- Installation details: https://sdbx.one/install/index.md
- Product overview: https://sdbx.one/index.md
- Product truth: https://sdbx.one/product-manifest.json
- LLM navigation: https://sdbx.one/llms.txt