# upbrr > Prepare, review, and submit private-tracker uploads This file contains all documentation content in a single document following the llmstxt.org standard. ## API reference upbrr exposes a versioned HTTP API for durable release workflows. The embedded OpenAPI document is the exact contract for the running binary. After starting the Web UI server, open: - Swagger UI: `http://localhost:7480/api/v1/docs` - OpenAPI 3.1 JSON: `http://localhost:7480/api/v1/openapi.json` When a base path is configured, prefix both routes, for example `http://localhost:7480/upbrr/api/v1/docs`. ## Authentication API requests use a persistent bearer token: ```http Authorization: Bearer ``` Create tokens from the CLI after the active database and `web-auth.json` have been initialized: ```powershell .\upbrr.exe api-token create --name "Release automation" --owner "automation" --scopes workflow:read,workflow:write ``` The plaintext token is returned only from the create command. Store it in a secret manager and never log it. List token metadata: ```powershell .\upbrr.exe api-token list ``` Revoke a token: ```powershell .\upbrr.exe api-token revoke ``` ## Scopes | Scope | Grants | | ------------------ | --------------------------------------------------------------------- | | `workflow:read` | Immutable workflow, operation, capability, and result reads. | | `workflow:write` | Preparation and non-execution workflow commands. | | `workflow:execute` | Commands that consume reviewed upload plans and can cause submission. | An omitted or empty scope selection grants all currently supported scopes. Prefer the smallest set. Keep `workflow:execute` separate from read-only monitoring where possible. The token owner value isolates durable workflows. Reuse one stable owner for one automation identity; do not mix unrelated operators under the same owner without intending to share that workflow namespace. ## Route groups The current API registers these top-level resources: | Route | Purpose | | ---------------------------- | --------------------------------------------------------------------------- | | `GET /api/v1/capabilities` | Discover contract and workflow capabilities. | | `POST /api/v1/uploads` | Start an upload workflow. | | `/api/v1/uploads/{id}/...` | Supply upload workflow feedback where defined. | | `POST /api/v1/continuations` | Continue a retained workflow from required actions. | | `/api/v1/workflows/{id}/...` | Read workflows and operations, issue commands, and retrieve media previews. | Methods, request bodies, response schemas, status codes, idempotency rules, and nested workflow routes can change as the alpha API evolves. Generate clients from the OpenAPI document shipped with the binary you run. ## Base-path example ```powershell $headers = @{ Authorization = "Bearer $env:UPBRR_API_TOKEN" } Invoke-RestMethod -Headers $headers -Uri "http://localhost:7480/api/v1/capabilities" ``` Keep the token in an environment variable or secret store. Do not paste it directly into scripts committed to source control. ## Browser session API Routes below `/api/auth`, `/api/app`, and `/api/events` serve the embedded Web UI and use browser-session authentication. They are not a substitute for the versioned bearer-token API. External integrations should use `/api/v1`. --- ## CLI reference ```text upbrr [options] ... upbrr serve [options] upbrr api-token [options] ``` On Windows, examples use `upbrr.exe`. Put options before input paths. Use executable help as the exact reference for your installed version: ```powershell .\upbrr.exe --help .\upbrr.exe serve --help .\upbrr.exe api-token create --help ``` ## Common operations Prepare one release: ```powershell .\upbrr.exe "D:\releases\Example.Release.2026.1080p-GRP" ``` Prepare without tracker submission or client injection: ```powershell .\upbrr.exe --debug --no-seed "D:\releases\Example.Release.2026.1080p-GRP" ``` Run duplicate and site checks without uploading: ```powershell .\upbrr.exe --site-check --trackers BLU,OE "D:\releases\Example.Release.2026.1080p-GRP" ``` Process at most five entries from a queue folder: ```powershell .\upbrr.exe --queue "D:\upload-queue" --limit-queue 5 ``` ## Interaction and safety | Option | Behavior | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `--debug` | Runs end-to-end preparation and payload preview without tracker submission. Client injection remains enabled unless `--no-seed` is set. | | `--log-level debug` | Changes logging verbosity only. It does not enable debug/non-submitting behavior. | | `--unattended` | Never prompts. Unsafe global ambiguity returns an error; tracker-specific manual prerequisites can block only that tracker. | | `--unattended_confirm` | Uses unattended defaults but permits required confirmation or manual-input prompts. | | `--no-seed` | Disables torrent-client injection. | :::danger Destructive maintenance `--cleanup` deletes all stored release content from the active database. `--delete-tmp` deletes stored database content for each supplied input before processing it. Back up state and verify the active config/database before using either option. ::: ## Config and application | Option | Aliases | Purpose | | --------------------------- | -------------------------- | ----------------------------------------------------------- | | `--config ` | `-config` | Use a config file path. | | `--export-config ` | `-export-config` | Export SQLite config to YAML and exit. | | `--export-config-plaintext` | `-export-config-plaintext` | Include plaintext secrets; requires `--export-config`. | | `--import-config ` | `-import-config` | Import `.py`, `.yaml`, `.yml`, or `.json` config and exit. | | `--create-auth` | `-create-auth` | Create `web-auth.json` beside the active database and exit. | | `--version` | `-version` | Print version and exit. | | `--cleanup` | `-cleanup` | Delete all stored release content and exit. | ## Execution | Option | Aliases | Purpose | | ------------------------- | ----------------------------- | ------------------------------------------------------- | | `--queue ` | `-queue` | Process an entire folder queue. | | `--limit-queue ` | `-limit-queue`, `-lq` | Limit queued items processed. | | `--site-check` | `-site-check`, `-sc` | Search/check sites without uploading. | | `--site-upload ` | `-site-upload`, `-su` | Process one tracker upload flow. | | `--debug` | `-debug` | Enable non-submitting debug mode. | | `--log-level ` | `-log-level` | Set `error`, `warn`, `info`, `debug`, or `trace`. | | `--upload-only` | `-upload-only` | Upload using prepared metadata cache only. | | `--delete-tmp` | `-delete-tmp`, `-dtmp` | Delete stored content for each input before processing. | | `--unattended` | `-unattended`, `-ua` | Run without prompts. | | `--unattended_confirm` | `-unattended_confirm`, `-uac` | Run unattended defaults with prompts allowed. | ## Tracker selection and IDs | Option | Aliases | Purpose | | -------------------------- | -------------------------- | ----------------------------------- | | `--trackers ` | `-trackers`, `-tk` | Use comma-separated trackers. | | `--trackers-remove ` | `-trackers-remove`, `-rtk` | Remove comma-separated trackers. | | `--ptp ` | `-ptp` | Supply a PTP torrent ID or URL. | | `--blu ` | `-blu` | Supply a BLU torrent ID or URL. | | `--aither ` | `-aither` | Supply an Aither torrent ID or URL. | | `--lst ` | `-lst` | Supply an LST torrent ID or URL. | | `--oe ` | `-oe` | Supply an OE torrent ID or URL. | | `--hdb ` | `-hdb` | Supply an HDB torrent ID or URL. | | `--btn ` | `-btn` | Supply a BTN torrent ID or URL. | | `--bhd ` | `-bhd` | Supply a BHD torrent ID or URL. | | `--ulcx ` | `-ulcx` | Supply a ULCX torrent ID or URL. | ## Release overrides | Option | Aliases | Purpose | | ----------------------------- | ------------------------------------------------- | ------------------------------------------------- | | `--category ` | `-category`, `-c` | Override category. | | `--type ` | `-type`, `-t` | Override release type. | | `--source ` | `-source` | Override source. | | `--resolution ` | `-resolution`, `-res` | Override resolution. | | `--tag ` | `-tag`, `-g` | Override group tag. | | `--service ` | `-service`, `-serv` | Override streaming service. | | `--distributor ` | `-distributor`, `-dist` | Override distributor. | | `--original-language ` | `-original-language`, `-ol` | Override original language. | | `--edition ` | `-edition`, `-repack` | Override edition text. | | `--season ` | `-season` | Override one season token, such as `5` or `S05`. | | `--episode ` | `-episode` | Override one episode token, such as `5` or `E05`. | | `--episode-title ` | `-episode-title`, `-manual-episode-title`, `-met` | Override episode title. | | `--manual-year ` | `-manual-year`, `-year` | Override release year. | | `--daily ` | `-daily` | Set daily episode air date. | | `--region ` | `-region`, `-reg` | Override disc region. | | `--no-season` | `-no-season` | Remove season and episode from name. | | `--no-year` | `-no-year` | Remove year from name. | | `--no-aka` | `-no-aka` | Remove AKA from name. | | `--no-tag` | `-no-tag` | Remove group tag from name. | | `--no-episode-title` | `-no-episode-title`, `-net` | Remove episode title from name. | | `--no-distributor` | `-no-distributor`, `-ndist` | Remove distributor. | | `--no-edition` | `-no-edition`, `-ne` | Remove edition from name. | | `--no-dub` | `-no-dub` | Remove dubbed tag from audio name. | | `--no-dual` | `-no-dual` | Remove dual-audio tag from audio name. | | `--dual-audio` | `-dual-audio` | Add dual-audio tag to audio name. | ## Metadata IDs | Option | Aliases | Purpose | | --------------- | --------- | ------------------- | | `--tmdb ` | `-tmdb` | Override TMDB ID. | | `--imdb ` | `-imdb` | Override IMDb ID. | | `--mal ` | `-mal` | Override MAL ID. | | `--tvdb ` | `-tvdb` | Override TVDB ID. | | `--tvmaze ` | `-tvmaze` | Override TVmaze ID. | ## Tracker overrides | Option | Aliases | Purpose | | --------------------- | ---------------------------- | ----------------------------------------- | | `--skip-dupe-check` | `-skip-dupe-check`, `-sdc` | Skip duplicate checking. | | `--skip-dupe-asking` | `-skip-dupe-asking`, `-sda` | Skip duplicate asking. | | `--double-dupe-check` | `-double-dupe-check`, `-ddc` | Run a double duplicate check. | | `--foreign` | `-foreign` | Mark a TIK release as foreign. | | `--opera` | `-opera` | Mark a TIK release as opera or musical. | | `--asian` | `-asian` | Mark a TIK release as Asian. | | `--disctype ` | `-disctype` | Override TIK disc type. | | `--commentary` | `-commentary`, `-mc` | Mark release as containing commentary. | | `--personalrelease` | `-personalrelease`, `-pr` | Mark release as personal. | | `--stream` | `-stream`, `-st` | Mark release as stream optimized. | | `--webdv` | `-webdv` | Mark release as WEB-DV. | | `--not-anime` | `-not-anime` | Force release to be treated as not anime. | | `--anon` | `-anon`, `-a` | Upload anonymously. | | `--draft` | `-draft`, `-dr` | Send to drafts where supported. | | `--modq` | `-modq`, `-mq` | Opt into mod queue where supported. | | `--channel ` | `-channel`, `-ch` | Override SPD channel. | ## Screenshots, images, and descriptions | Option | Aliases | Purpose | | ---------------------------- | ----------------------------------- | ----------------------------------------------------- | | `--screens ` | `-screens`, `-s` | Set screenshot count. | | `--manual_frames ` | `-manual_frames`, `-mf` | Use comma-separated frame numbers. | | `--comparison ` | `-comparison`, `-comps` | Set one comparison folder or comma-separated folders. | | `--comparison_index ` | `-comparison_index`, `-comps_index` | Select the primary comparison index. | | `--menu-images ` | `-menu-images` | Import manually captured disc-menu screenshots. | | `--get-dvd-menus` | `-get-dvd-menus` | Capture distinct menus from extracted DVD `VIDEO_TS`. | | `--imghost ` | `-imghost`, `-ih` | Override image host. | | `--skip-imagehost-upload` | `-skip-imagehost-upload`, `-siu` | Skip automatic image-host uploads. | | `--descfile ` | `-descfile`, `-df` | Use a custom description file. | | `--desclink ` | `-desclink`, `-pb` | Use a custom description link. | ## Client and torrent | Option | Aliases | Purpose | | ------------------------ | ---------------------------------- | ---------------------------------------------------------------- | | `--client ` | `-client` | Override torrent client. | | `--qbit-tag ` | `-qbit-tag`, `-qbt` | Override qBittorrent tag. | | `--qbit-cat ` | `-qbit-cat`, `-qbc` | Override qBittorrent category. | | `--force-recheck` | `-force-recheck`, `-frc` | Force recheck of matched qBittorrent torrents before validation. | | `--no-seed` | `-no-seed`, `-ns` | Do not inject into torrent clients. | | `--skip_auto_torrent` | `-skip_auto_torrent`, `-sat` | Skip automated torrent-client searching. | | `--keep-folder` | `-keep-folder`, `-kf` | Keep a supplied folder instead of selecting its video file. | | `--onlyID` | `-onlyID` | Only retrieve tracker metadata IDs. | | `--infohash ` | `-infohash`, `-th`, `-torrenthash` | Override the v1 info hash. | | `--max-piece-size ` | `-max-piece-size`, `-mps` | Set maximum torrent piece size in MiB. | | `--nohash` | `-nohash`, `-nh` | Reuse existing torrents only; do not generate a new torrent. | | `--rehash` | `-rehash`, `-rh` | Force generation of a fresh torrent. | ## `serve` ```text upbrr serve [options] ``` | Option | Purpose | | -------------------------- | -------------------------------------------------------- | | `--config ` | Use a config file path. | | `--addr ` | Set the complete listen address. | | `--host ` | Set the listen host. | | `--port ` | Set the listen port. | | `--base-url ` | Set the external Web UI URL or path prefix. | | `--persist-listen` | Persist listen host and port to `web-config.json`. | | `--persist-web-config` | Persist supplied Web UI serve settings. | | `--dev-no-auth` | Disable Web auth for local development on loopback only. | See [Web server and reverse proxy](../configuration/web-server.md) for precedence and proxy examples. ## `api-token` Create a persistent bearer token: ```powershell .\upbrr.exe api-token create --name "Release automation" --owner "automation" --scopes workflow:read,workflow:write ``` `--scopes` accepts `workflow:read`, `workflow:write`, and `workflow:execute`. Omitting it grants all supported scopes. The plaintext token is returned only when created; store it in a secret manager. List safe token metadata: ```powershell .\upbrr.exe api-token list ``` Revoke by token ID: ```powershell .\upbrr.exe api-token revoke tok_example ``` Create options also include `--config`, `--name`, `--owner`, and `--scopes`. List and revoke accept `--config`. See the [API reference](../api/index.md) before granting `workflow:execute`. --- ## Configuration The Web UI **Settings** page is the normal configuration surface. Runtime settings are persisted in SQLite; YAML and JSON are import/export formats rather than the primary state store. ## State location Without `XDG_CONFIG_HOME`, upbrr uses: ```text Windows: %USERPROFILE%\.upbrr\db.sqlite Linux/macOS: ~/.upbrr/db.sqlite ``` With `XDG_CONFIG_HOME`, the preferred path is: ```text $XDG_CONFIG_HOME/upbrr/db.sqlite ``` When an older database already exists at `$XDG_CONFIG_HOME/.upbrr/db.sqlite`, upbrr keeps using it so an upgrade does not orphan existing state. The Docker image sets `XDG_CONFIG_HOME=/config`, so new containers use `/config/upbrr/db.sqlite`. Existing `/config/.upbrr/db.sqlite` installations remain discoverable. Database-adjacent files include: | Path | Purpose | | ----------------- | ------------------------------------------------------------------------- | | `web-auth.json` | Web authentication, browse policy, and key material for encrypted secrets | | `web-config.json` | Persisted Web UI listen and proxy settings | | `cookies/` | Legacy tracker cookie import location | Back up the whole state directory, not only `db.sqlite`. ## Setting groups | Group | Controls | | -------------------- | ---------------------------------------------------------------------- | | Main settings | updates, metadata API access, input history, scene detection | | Image hosting | host priority and host credentials | | Metadata | torrent discovery, playlist selection, cached images, external lookups | | Screenshot handling | count, concurrency, tone mapping, overlays, DVD menu limits | | Description settings | image layout, limits, headers, signatures, optional artwork | | Client setup | default, searching, and injecting torrent clients | | Arr integration | Sonarr, Radarr, and mapped media directories | | Torrent creation | hashing threads, piece-size preference, rehash scheduling | | Post upload | injection delay, tracker concurrency, messages, cross-seeding | | Logging | level, file output, retention size and count | | Trackers | defaults, preferred tracker, auth, and tracker-owned options | | Torrent clients | qBittorrent and other registered client settings | Fields shown for each tracker come from the active tracker catalog. Configure only fields presented for that tracker. See the [Web UI Settings reference](../web-ui/settings/index.md) for section-by-section field behavior. ## Import configuration Import Upload Assistant Python, upbrr YAML, or upbrr JSON: ```powershell .\upbrr.exe --import-config ".\config.yaml" ``` Import merges the supplied data with current defaults before saving it. Review warnings and inspect Settings afterward. ## Export configuration The default YAML export preserves secret values in encrypted form: ```powershell .\upbrr.exe --export-config ".\config-export.yaml" ``` Plaintext export is explicit: ```powershell .\upbrr.exe --export-config ".\config-export.yaml" --export-config-plaintext ``` :::danger Plaintext secrets A plaintext export can contain tracker credentials, API keys, passkeys, client passwords, and service tokens. Restrict access, never attach it to an issue, and delete it securely when finished. ::: The Web UI can import and export configuration from **Settings**. ## Configuration safety - Never copy raw configuration, cookies, announce URLs, or API responses into public reports. - Keep `web-auth.json` with the database when moving an installation; encrypted secrets depend on its key material. - Use the **Logging** page for sanitized diagnostics rather than exposing config values. - Test tracker authentication after changing credentials. - Use a dry run after changes to tracker, image-host, torrent, or client behavior. Web listen settings have separate precedence and storage. See [Web server and reverse proxy](./web-server.md). --- ## Web server and reverse proxy Start the embedded Web UI with: ```powershell .\upbrr.exe serve ``` Defaults: | Setting | Default | | ------------------ | ------------- | | Host | `localhost` | | Port | `7480` | | Open browser | enabled | | External base path | `/` | | Session lifetime | 1,440 minutes | ## Precedence Serve settings resolve in this order: 1. CLI flags; 2. `UPBRR_WEB_*` environment variables; 3. `web-config.json` beside the active database; 4. defaults. Supported environment variables: | Variable | Purpose | | --------------------------- | --------------------------------------------------- | | `UPBRR_WEB_HOST` | Listen host | | `UPBRR_WEB_PORT` | Listen port | | `UPBRR_WEB_BASE_URL` | External URL or path prefix | | `UPBRR_WEB_OPEN_BROWSER` | Whether to open a browser at startup | | `UPBRR_WEB_TRUSTED_PROXIES` | Comma-separated trusted proxy addresses or networks | Use `--persist-web-config` to save supplied `serve` settings. Add `--persist-listen` when the listen host or port should also be saved. ```powershell .\upbrr.exe serve --host 127.0.0.1 --port 7480 --persist-listen --persist-web-config ``` ## First-run authentication and browse policy The first browser connection creates an administrator account. The same setup asks for one or more browse roots or explicit unrestricted browsing. Browse roots restrict browser-driven folder selection and file import. They do not restrict a direct CLI input path. Store them in `web-auth.json`, separate from imported application configuration. `--dev-no-auth` disables browser authentication only on loopback hosts and is intended for local development. Do not use it for a network-accessible deployment. ## Subdomain proxy A dedicated subdomain keeps upbrr at the web root, so no base-path setting is needed: ```nginx server { server_name upbrr.example.test; location / { proxy_pass http://localhost:7480/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffering off; } } ``` Start normally: ```powershell .\upbrr.exe serve ``` ## Path-prefix proxy When the browser sees `https://example.test/upbrr/`, tell upbrr the same external base path: ```powershell .\upbrr.exe serve --base-url https://example.test/upbrr/ ``` For containers: ```yaml environment: - UPBRR_WEB_BASE_URL=/upbrr/ - UPBRR_HEALTHCHECK_URL=http://127.0.0.1:7480/upbrr/api/auth/status ``` Retain the prefix when proxying: ```nginx server { server_name example.test; location = /upbrr { return 301 /upbrr/; } location /upbrr/ { proxy_pass http://localhost:7480/upbrr/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffering off; } } ``` The supported layout keeps `/upbrr/` on both sides. Rewriting only some HTML, API, event-stream, cookie, or asset paths causes partial failures. ## HTTPS termination When a trusted reverse proxy terminates HTTPS and forwards HTTP to upbrr, add its address or network to `trusted_proxies` in `web-config.json` or `UPBRR_WEB_TRUSTED_PROXIES`. upbrr trusts forwarded scheme information only from configured proxies when deciding whether cookies require the secure flag. Do not trust broad networks unless every host in them is under your control. --- ## Contributing and support Use these project channels: - [GitHub issues](https://github.com/autobrr/upbrr/issues) for reproducible defects and feature proposals; - [autobrr Discord](https://discord.autobrr.com) for community discussion; - [GitHub pull requests](https://github.com/autobrr/upbrr/pulls) for reviewed changes. Discuss large behavior changes before implementation. Read the repository [contribution guide](https://github.com/autobrr/upbrr/blob/main/CONTRIBUTING.md) and applicable `AGENTS.md` files. ## Report a defect Include: 1. upbrr version and build identifier; 2. operating system and installation method; 3. affected surface: CLI, Web UI, API, tracker, image host, or client; 4. shortest reproduction; 5. expected and actual outcome; 6. sanitized logs. Use synthetic release data such as `Example.Release.2026.1080p-GRP` and `tt1234567`. Never include credentials, cookies, passkeys, announce URLs, OTP data, plaintext config exports, private tracker rules, or raw secret-bearing responses. ## Edit this site Public documentation lives in `documentation/`. Internal planning material under `docs/` is separate. From the repository root: ```powershell pnpm --dir documentation install --frozen-lockfile pnpm --dir documentation run start ``` Before opening a pull request: ```powershell pnpm --dir documentation run format:check pnpm --dir documentation run typecheck pnpm --dir documentation run build git diff --check ``` Do not commit `documentation/build/`, `documentation/.docusaurus/`, or `documentation/node_modules/`. ## Documentation standards - Verify commands, flags, defaults, endpoints, and fields against current code or executable output. - Give each page one reader goal. - Separate tutorials, task guides, reference, and explanation. - Keep examples synthetic and safe to share. - Add recovery guidance where a task can fail. - Update navigation and related pages when changing a shared contract. ## Code contributions Follow the checks selected by the nearest `AGENTS.md`. Tracker work must also follow [ADDING_TRACKERS.md](https://github.com/autobrr/upbrr/blob/main/ADDING_TRACKERS.md). Do not weaken tests or policy checks to make a change pass. upbrr is licensed under GPL-2.0-or-later. --- ## Installation upbrr ships as a single binary with the Web UI embedded. Release automation builds these targets: | Operating system | Architectures | | ---------------- | ------------------- | | Windows | amd64, arm64 | | Linux | amd64, arm64, armv7 | | macOS | amd64, arm64 | Docker images are published for Linux amd64 and arm64. ## Release binary 1. Open [GitHub Releases](https://github.com/autobrr/upbrr/releases). 2. Download the archive matching your operating system and CPU. 3. Extract it into a directory owned by your user. 4. Verify the executable starts: ```powershell .\upbrr.exe --version ``` 5. Start the Web UI: ```powershell .\upbrr.exe serve ``` On Linux or macOS, use `./upbrr` instead of `.\upbrr.exe`. If required, make it executable with `chmod +x ./upbrr`. ## FFmpeg FFmpeg is required for screenshot generation. - **Windows:** install FFmpeg and add its executable directory to `PATH` before starting upbrr. - **Linux:** install FFmpeg through your distribution package manager. - **macOS:** install with Homebrew using `brew install ffmpeg`, then start upbrr from an environment that includes Homebrew's binary directory. Automatic DVD menu capture has stricter requirements. The selected FFmpeg must expose the `dvdvideo` demuxer and its menu-coordinate options. upbrr checks this at runtime; a version number alone does not prove support. ## Docker Compose The repository includes a maintained [Compose example](https://github.com/autobrr/upbrr/blob/main/example-docker-compose.yml). Save it as `docker-compose.yml`, replace both host paths, then start it: ```bash docker compose up -d ``` The image: - serves the Web UI on `0.0.0.0:7480`; - stores application state below the `/config` volume; - expects release data below mounted paths such as `/data`; - runs as uid and gid `1000:1000` by default; - includes FFmpeg and the fonts needed by screenshot overlays. On Linux, create bind-mount directories before starting and give the container user read/write access: ```bash mkdir -p /path/to/config /path/to/torrents sudo chown -R 1000:1000 /path/to/config /path/to/torrents ``` For production, replace `latest` with a specific release tag. If you publish port `7480` on all interfaces, finish first-run account setup promptly. Bind to `127.0.0.1:7480:7480` or use a reverse proxy when LAN access is not required. ## Next step Complete the [quick start](./quick-start.md). For subdomain or path-prefix proxying, see [Web server and reverse proxy](../configuration/web-server.md). --- ## Migrate from Upload Assistant upbrr accepts Upload Assistant `config.py` files through its config importer. Imported settings are a starting point; unsupported or renamed options can require manual correction. ## Direct import Use direct import to convert and save the configuration into upbrr's database: ```powershell .\upbrr.exe --import-config "C:\path\to\Upload-Assistant\data\config.py" ``` The importer accepts: - Upload Assistant `.py` files; - upbrr `.yaml` and `.yml` files; - upbrr `.json` files. Read every warning. Unknown legacy keys, unsupported tracker fields, and unsupported image-host settings can be omitted or adjusted. The Web UI also provides config import in **Settings**. ## Convert to YAML first Use the repository converter when you want to inspect the result before import: ```powershell py .\scripts\convert_ua_config.py "C:\path\to\Upload-Assistant\data\config.py" -o ".\config.converted.yaml" ``` Review the generated file, then import it: ```powershell .\upbrr.exe --import-config ".\config.converted.yaml" ``` ## Migrate tracker cookies Copy legacy `.txt` or `.json` cookie files into a `cookies` directory beside the active `db.sqlite`, then restart upbrr. Successfully migrated legacy files are removed. Verify tracker authentication from **Settings** before preparing a live upload. ## Restore Web UI browse access Browse roots are not part of imported application config. They are stored in `web-auth.json` beside the database because they control which host paths the browser may access. After import, complete first-run Web UI setup or update the browse policy. Existing browse roots remain unchanged when application config is imported. ## Validate the migration Check metadata credentials, trackers, image hosts, torrent clients, screenshot settings, and post-upload behavior. Then run one workflow with `--debug --no-seed` or use the Web UI dry run before submitting anything. --- ## Quick start This tutorial starts the embedded Web UI and takes one release through a non-submitting review. ## Prerequisites Have these ready: - an installed upbrr binary or running container; - FFmpeg available to the upbrr process for screenshot generation; - a release path that upbrr can read; - the credentials required by your trackers and image hosts; - optional torrent-client details for search and injection. Most tracker workflows also need a TMDB API key. Requirements vary by tracker. ## 1. Start upbrr From a Windows PowerShell terminal beside the extracted binary: ```powershell .\upbrr.exe serve ``` upbrr listens on `localhost:7480` by default and opens a browser. If it does not open automatically, visit [http://localhost:7480](http://localhost:7480). For Linux or macOS, run the equivalent executable: ```bash ./upbrr serve ``` ## 2. Secure browser access The first-run screen creates the administrator account. Choose a unique password. Then set one or more browse roots. These roots limit which host folders the browser can select. Use the narrowest folders containing your releases, such as `D:\Media` and `E:\Downloads`. Unrestricted host browsing is available but broadens access. :::caution Network exposure Complete first-run setup before exposing port `7480` to other systems. Anyone who can reach an unconfigured instance can reach the setup screen. ::: ## 3. Configure integrations Open **Settings** and configure only the services you use: 1. add the metadata credentials required by your trackers; 2. choose default trackers and configure their credentials; 3. configure at least one permitted image host; 4. configure screenshot behavior; 5. optionally configure torrent-client search and injection; 6. save settings; 7. test tracker authentication where the tracker exposes that action. See [Configuration](../configuration/index.md) for storage, import, export, and setting groups. ## 4. Prepare a release 1. Open **Input**. 2. Select `D:\releases\Example.Release.2026.1080p-GRP` or enter its path. 3. Select the intended trackers. 4. fetch metadata; 5. review the parsed media fields and generated release name; 6. continue through duplicate checks, screenshots, image uploads, and descriptions; 7. use **Dry Run** or payload preview on the upload stage; 8. do not submit until every tracker view matches its current rules. ## 5. Try the CLI safety path The equivalent non-submitting CLI run is: ```powershell .\upbrr.exe --debug --no-seed "D:\releases\Example.Release.2026.1080p-GRP" ``` `--debug` suppresses tracker submission. `--no-seed` also prevents torrent-client injection. ## Expected result You should have reviewed metadata, duplicate evidence, images, descriptions, and tracker payload previews without submitting an upload or injecting a torrent. Next, learn the [upload workflow](../workflow/index.md) and the [required manual checks](../workflow/index.md#final-review-checklist). --- ## Upgrading upbrr applies forward-only SQLite migrations during startup. Back up application state before running a newer version. ## 1. Stop upbrr Stop the binary, service, or container so the database is not changing while copied. ## 2. Back up the state directory Back up the directory containing `db.sqlite`. Keep adjacent files with it, especially: - `web-auth.json`, which protects browser authentication and encrypted application secrets; - `web-config.json`, when persisted serve settings are used; - the `cookies` directory, when legacy cookie import files have not yet been migrated. Default locations are described in [Configuration](../configuration/index.md#state-location). ## 3. Install the new version ### Binary Download the matching archive from [GitHub Releases](https://github.com/autobrr/upbrr/releases) and replace the old executable. Keep the state directory unchanged. ### Docker Update the pinned image tag, then pull and recreate the container: ```bash docker compose pull docker compose up -d ``` Keep the same `/config` volume. ## 4. Verify startup 1. start upbrr; 2. check startup output for migration or configuration errors; 3. sign in to the Web UI; 4. confirm Settings, tracker authentication status, history, and browse roots; 5. select **Skip client injection**, then run **Dry Run** before the next live upload. Dry Run suppresses tracker submission; the skip option prevents torrent injection. For CLI verification, use `--debug --no-seed` (`-ns`). :::caution Downgrades Do not assume an older binary can use a database migrated by a newer binary. To roll back safely, stop upbrr and restore the matching pre-upgrade state backup before starting the older version. ::: --- ## Introduction upbrr is an upload preparation app for private-tracker workflows. It combines metadata, duplicate checks, screenshots, image hosting, descriptions, tracker payload review, submission, and torrent-client injection in one workspace. :::warning Alpha software Quality-check every upload. Confirm the generated name, category, type, source, resolution, edition, description, images, torrent contents, and client settings against current tracker rules before submission. ::: ## Intended audience upbrr is for uploaders who already understand: - release naming and media classification; - tracker categories, types, and upload rules; - duplicate and trumping decisions; - screenshot and description requirements; - torrent creation, cross-seeding, and client injection. It guides those tasks. It does not replace tracker rules, staff direction, or operator judgment. ## What upbrr does A normal workflow can: 1. inspect a release folder or file; 2. fetch metadata and let you correct it; 3. prepare tracker-specific upload and search names; 4. run duplicate searches and eligibility checks; 5. generate or import screenshots and disc-menu images; 6. upload selected images to configured hosts; 7. build and preview tracker descriptions; 8. prepare immutable tracker payload previews; 9. submit approved uploads; 10. retain tracker-registered torrents and inject them into configured clients. The embedded Web UI and CLI share the same configuration, preparation services, tracker adapters, and durable workflow state. ## Safety boundaries - Duplicate results and tracker warnings need manual review. - `--debug` runs the workflow without tracker submission. It can still perform local and remote preparation work and inject into clients unless `--no-seed` is also set. - `--unattended` never prompts. Missing global decisions stop the run; tracker-specific manual prerequisites can leave only that tracker blocked. - Tracker credentials, cookies, and API keys must never appear in issue reports or shared diagnostics. Continue with the [quick start](./getting-started/quick-start.md), or read the [workflow explanation](./workflow/index.md) first. --- ## Trackers upbrr's tracker catalog is built from registered tracker implementations. The Web UI renders each tracker's supported settings and capabilities from that catalog. ## Configure a tracker 1. Open **Settings**. 2. Open the tracker section. 3. Enter only the requested credentials and options. 4. save settings; 5. import cookies, sign in, or test authentication when those actions are available; 6. add the tracker to default selection only after it reports ready. Auth requirements vary. A tracker can require an API key, passkey, cookie session, username/password login, 2FA, or a supported combination. upbrr stores managed tracker cookies encrypted in SQLite. Never paste tracker credentials, cookies, announce URLs, OTP secrets, or raw auth failures into issues or chat. ## Defaults and per-run selection - **Default trackers** seed the initial tracker set. - **Preferred tracker** influences workflows that need one preferred source of tracker data. - CLI `--trackers` selects a comma-separated set for one run. - CLI `--trackers-remove` removes trackers from that run. - The Web UI lets you select trackers from the Input page. The final upload authority is the exact tracker subset approved after duplicate review. Later stages must not silently add disabled, blocked, or unapproved trackers. ## Duplicate checks and rules Tracker adapters normalize duplicate results into a common review surface. A tracker can return: - a completed search with zero or more matches; - a not-run result with a reason, such as missing auth or metadata; - an attempted search failure. Rule and validation outcomes can block a live upload while still allowing debug preparation so you can inspect later stages. Subjective or incomplete tracker rules remain manual decisions. `--skip-dupe-check` and similar bypasses remove safeguards. Use them only when you have manually completed the equivalent tracker checks. ## Names and payloads upbrr resolves tracker-specific upload and search names before duplicate checking. Review the projected name for every tracker. The eventual payload uses that reviewed name rather than deriving a new name at submission time. Tracker-specific categories, source/type mappings, descriptions, media selection, questionnaires, and auth flows remain owned by the tracker adapter. A successful mapping does not prove the upload complies with every current site rule. ## Image hosts and clients Trackers can restrict usable image hosts or select tracker-specific image/client overrides. Configure a compatible host before media preparation. Confirm the final hosted links and client injection settings per tracker. ## Add or update tracker support Tracker implementation work requires registry, auth, naming, duplicate-search, validation, payload, and test contracts. Read [ADDING_TRACKERS.md](https://github.com/autobrr/upbrr/blob/main/ADDING_TRACKERS.md) before changing code. For a tracker defect, report the smallest sanitized reproduction. Omit private rules, credentials, response bodies, and private URLs unless tracker staff have authorized publication. --- ## Troubleshooting Start with the shortest failing operation and the **Logging** page. Increase log level only long enough to reproduce the problem, then restore normal verbosity. ## Web UI does not open 1. Run `upbrr serve --help` and verify the intended host and port. 2. Check startup output for `listen` errors. 3. Open `http://localhost:7480` manually for the default configuration. 4. If using Docker, confirm the container is healthy and port `7480` is published. 5. If another process owns the port, select another with `--port`. The default host is `localhost`, so another machine cannot connect unless you deliberately bind a network address or use Docker's `0.0.0.0` default. ## First-run setup is exposed Stop the instance or restrict its port to loopback until setup is complete. First-run account creation is reachable by anyone who can reach an unconfigured instance. ## A release folder is missing from the browser - Confirm the path is inside a configured browse root. - Confirm the upbrr process can read the folder. - In Docker, mount the folder and select its container path, such as `/data/...`. - Remember that config import does not import browse roots. Do not enable unrestricted browsing solely to hide a mount or permission error. ## A reverse-proxied page partly works If HTML loads but assets, login, API calls, or live progress fail under `/upbrr/`: 1. set `--base-url /upbrr/` or `UPBRR_WEB_BASE_URL=/upbrr/`; 2. keep `/upbrr/` on both sides of `proxy_pass`; 3. inspect browser requests for `/upbrr/api/...` and `/upbrr/assets/...`; 4. disable proxy buffering for live event streams; 5. configure trusted proxies when HTTPS terminates upstream. See the [reverse proxy guide](../configuration/web-server.md#path-prefix-proxy). ## FFmpeg is not found Run `ffmpeg -version` in the same environment that starts upbrr. On Windows, add FFmpeg's directory to `PATH` before starting upbrr or its service. Containers already include FFmpeg. The Web UI **Application Details** surface reports detected FFmpeg capability without exposing the local executable path. ## Automatic DVD menu capture fails Automatic capture accepts an extracted DVD directory containing `VIDEO_TS`, or `VIDEO_TS` itself. It does not accept ISO images, optical drives, or Blu-ray menus. The selected FFmpeg must expose the `dvdvideo` demuxer plus `menu`, `menu_lu`, `menu_vts`, `pgc`, and `pg`. Encrypted, protected, unreadable, region-restricted, or corrupt inputs can still fail. upbrr does not provide CSS decryption. Use manual disc-menu image import when automatic capture is not available. ## Tracker authentication is blocked 1. Open the tracker in **Settings**. 2. confirm every required field is present; 3. import a current cookie or use the supported login flow; 4. complete 2FA when requested; 5. run the tracker auth test; 6. retry preparation. Upload preflight does not silently log in or mutate auth state. Fix auth on the dedicated Settings surface. ## No screenshots or image links - Confirm FFmpeg access and screenshot count. - Confirm the chosen image host is configured and allowed by the tracker. - Review host-specific failure messages without copying credentials or raw responses. - Check `min_successful_image_uploads`: zero requires the whole batch to succeed; a positive value permits a partially successful batch only after that many images publish. - Use `--skip-imagehost-upload` only when you will supply valid hosted images another way. ## Config import reports warnings Warnings can identify unknown legacy keys, unsupported tracker fields, or unsupported image-host settings. Open Settings and correct each affected group. An import warning is not proof that the remaining configuration is ready for live upload. ## Unattended mode stops `--unattended` never prompts. It stops when a workflow-global decision or unsafe ambiguity needs operator input. Use `--unattended_confirm` only when prompts are acceptable, or provide the missing input explicitly. A tracker-specific manual prerequisite can block that tracker while other viable tracker lanes continue. ## Safe issue reports Include: - upbrr version and operating system; - binary or Docker installation; - the shortest reproduction using `Example.Release.2026.1080p-GRP`; - sanitized logs around the failure; - expected and actual stage outcome. Exclude config exports, API keys, passwords, cookies, passkeys, announce URLs, OTP data, private tracker pages, and raw request or response bodies. --- ## Web UI The Web UI is embedded in the upbrr binary and uses the same preparation, tracker, configuration, and persistence services as the CLI. Start it with: ```powershell .\upbrr.exe serve ``` The default address is [http://localhost:7480](http://localhost:7480). ## First-run setup Create the administrator account, then choose one or more host browse roots. Browse roots control which folders the browser can open for release selection and file import. Use a dedicated account password. Do not expose an unconfigured instance to an untrusted network. ## Release workspace The left navigation follows the release workflow. Some pages appear or unlock only when their input exists. | Page | Purpose | | ----------------- | ------------------------------------------------------------------------ | | **Input** | Choose the source path, trackers, metadata IDs, and preparation options. | | **Tracker Data** | Review tracker-derived metadata when available. | | **Blu-ray** | Select Blu-ray playlist or candidate data when the source requires it. | | **Dupe Check** | Review per-tracker search results, rules, and candidate upload names. | | **Screenshots** | Generate, import, order, and select screenshots. | | **Disc Menus** | Capture DVD menus automatically or import disc-menu images. | | **Upload Images** | Publish selected images through configured hosts. | | **Descriptions** | Build and inspect tracker-specific rendered descriptions. | | **Upload** | Preview payloads, dry run, approve eligible trackers, and submit. | Navigation guards prevent later operations from silently using missing or stale prerequisites. When a page is unavailable, read the notice and return to the required stage. ## Settings Use **Settings** to manage: - metadata services; - tracker defaults, credentials, auth status, and tracker-owned fields; - image-host priority and credentials; - screenshot and description behavior; - torrent creation and client integration; - post-upload behavior; - config import and export. Saving settings activates the new runtime configuration. Recheck tracker auth and run a dry run after changing credentials or upload behavior. See the [Settings reference](./settings/index.md) for every section, field behavior, and verification guidance. ## History **History** shows retained releases and lets you reopen their overview. Deleting a release from History removes its stored release state; it does not delete the source media. ## Logging **Logging** shows recent sanitized application logs, a live stream, runtime verbosity, and file-rotation settings. Logs are designed for safer sharing, but inspect them before posting. Never include configuration exports, cookies, credentials, announce URLs, or private API payloads. See [Logging](./logging.md) for persistence, filtering, rotation, and buffer behavior. ## Host browser The host browser lists only configured roots unless unrestricted browsing was explicitly enabled. If a valid folder is missing: 1. verify the upbrr process or container can read it; 2. verify the path is mounted into the container when using Docker; 3. update browse roots through the Web UI auth/browse policy; 4. use the path as visible inside the container, not the host-only path. Imported application config does not change browse roots. ## Safe first use Use **Dry Run** on the Upload page and disable client injection for the first test. Compare every tracker tab with the tracker's current upload form and rules before allowing submission. See [Upload workflow](../workflow/index.md) for stage ownership and review boundaries. --- ## Logging Open **Logging** from the main navigation to configure application logging and inspect recent activity. ## Runtime settings These edits require **Save** before they become active. | Field | Default | Effect | | ------------------ | ------- | --------------------------------------------------------------------------------------------------------------- | | **Level** | `info` | Sets runtime verbosity from `trace` through `error`. `trace` records the most detail. | | **File enabled** | Off | Writes application logs to the displayed host path. | | **Max total size** | `20 MB` | Sets the approximate total file budget. The per-file rotation threshold is this value divided by **Max files**. | | **Max files** | `3` | Sets the file-rotation depth used with the total-size budget. | File logging requires positive **Max total size** and **Max files** values. The log path is `/logs/upbrr.log`; displaying a path does not mean file logging is enabled. ## Live viewer **Connected** means the browser is receiving the live stream. The page first loads up to 1,000 recent sanitized entries, then appends new entries. - Level checkboxes and search filter only the current display; they do not change runtime logging. - **Clear** empties the browser buffer only. It does not delete the log file or clear the backend buffer. - With **Auto-scroll** enabled, the browser retains the latest 1,000 entries. With it disabled, the buffer can grow to 10,000 entries before dropping the oldest entries and showing a warning. - A muted pattern hides exact whole-message matches in the viewer. Adding, clicking, or removing a mute persists it immediately without **Save**; it does not suppress the underlying log event. The viewer receives centrally sanitized messages, but inspect entries before sharing them. Never publish credentials, cookies, tokens, announce URLs, filesystem details, or private tracker data. --- ## API Tokens Use **Settings → API Tokens** for external clients of the versioned `/api/v1` release-workflow API. Token actions persist immediately and do not use the page-level **Save** button. ## Generate a token 1. Enter a descriptive **Name**. 2. Enter a stable **Owner** for the automation identity. 3. Select the minimum required scopes. 4. Select **Generate token**. 5. Copy the plaintext token immediately into a secret manager. The plaintext token is shown once. Only its hash persists in `web-auth.json`; it cannot be recovered later. Tokens with the same owner share the same owner-scoped durable workflows. | Scope | Grants | | ------------------ | --------------------------------------------------------------------- | | `workflow:read` | Workflow, operation, capability, and result reads. | | `workflow:write` | Preparation and non-execution workflow commands. | | `workflow:execute` | Commands that consume reviewed upload plans and can cause submission. | Keep `workflow:execute` out of monitoring-only integrations. Send the token as: ```http Authorization: Bearer ``` See the [API reference](../../api/index.md) for routes and OpenAPI documentation. ## Revoke a token Select **Revoke**, then confirm. Revocation rejects the next request and cannot be undone. Create a replacement token before revoking when an integration needs uninterrupted access. API token metadata is not part of configuration export. Never place a plaintext token in source control, logs, screenshots, or support reports. --- ## Application Details **Settings → Application Details** is read-only. It reports the current process rather than persisted configuration. | Detail | Meaning | | -------------------- | ------------------------------------------------------------------ | | **Project** | Link to `autobrr/upbrr`. | | **Version** | Release version reported by the binary. | | **Build** | Build identifier compiled into the binary. | | **Go Runtime** | Go version used by the process. | | **DVD Menu Engine** | Detected DVD menu engine version. | | **FFmpeg DVD Menus** | Available, incompatible, or unavailable, with the detected reason. | | **FFmpeg Version** | FFmpeg version seen by the DVD menu capability check. | | **Platform** | Runtime OS and architecture, shown as `GOOS/GOARCH`. | | **Uptime** | Elapsed process uptime. | Auth settings, bind addresses, and storage paths are intentionally excluded. For a support request, share the relevant version, build, platform, capability message, and sanitized logs; never attach raw configuration or credentials. --- ## Arr settings Use **Settings → Arr** to let upbrr match a source path against Sonarr for TV or Radarr for movies. A match supplies non-authoritative IDs, year, genres, and release-group evidence to preparation. ## Configure Sonarr or Radarr 1. Turn on **Use Sonarr** and/or **Use Radarr**. 2. Enter the service base URL and API key in the unnumbered fields. 3. Use **Show advanced** for up to three additional URL and API-key pairs per service. 4. Select **Save**. Each instance requires both a URL and API key. Incomplete pairs are ignored. Instances are checked in this order: unnumbered, `1`, `2`, then `3`; lookup stops when one returns useful evidence. Use the URL reachable from the upbrr process. In Docker, `localhost` refers to the upbrr container, not the host or another container. Enter a base URL such as `http://sonarr:8989`, without adding an API route. API keys are secrets and appear as `[REDACTED]` after saving. :::note Compatibility fields **Emby dir** and **Emby TV dir** remain in the schema but have no current runtime reader. ::: ## Verify the change There is no connection-test button in this section. Save, prepare a source already known to the configured Arr service, then inspect its metadata and sanitized logs. A failed or empty Arr lookup does not block preparation; upbrr continues with other evidence. --- ## Client Handling settings Use **Settings → Client Handling** after creating entries under [Torrent Clients](./torrent-clients.md). The selectors contain configured client names and reject stale references when saved. | Field | Purpose | | --------------------- | ---------------------------------------------------------------------------------- | | **Default client** | Fallback client for search and injection when their dedicated selectors are empty. | | **Injected clients** | Set of clients that receive successfully registered torrents. | | **Searching clients** | qBittorrent or qui-backed clients searched for existing reusable torrents. | ## Selection order Injection uses the first applicable source: 1. workflow or tracker-specific client override; 2. **Injected clients**; 3. **Default client**; 4. the only configured client, when exactly one exists. Search uses the first applicable source: 1. workflow client override; 2. **Searching clients**; 3. **Default client**; 4. all configured qBittorrent and qui-backed clients. Watch-folder clients can receive torrent files but are not used for torrent search. Removing a Torrent Clients entry in the Web UI also clears its global and tracker references before save. ## Verify the change Save, prepare a source already present in the intended search client, and inspect client-discovery results. For first injection, keep **Skip client injection** enabled during review, then perform one controlled upload after confirming paths, categories, and tags. --- ## Description settings Use **Settings → Description** to control shared description builders. Trackers can apply their own markup and field rules, so confirm each rendered result on **Descriptions**. ## Layout and artwork | Field | Default | Effect | | --------------------- | ------- | ------------------------------------------------------------------------------------------- | | **Add logo** | Off | Adds a TMDB logo when one is available. Requires TMDB enrichment. | | **Logo size** | `300` | Sets the rendered logo width; non-positive values resolve to `300`. | | **Logo language** | Empty | Supplies preferred TMDB logo languages. | | **Thumbnail size** | `350` | Sets shared screenshot and disc-menu thumbnail width; non-positive values resolve to `350`. | | **Screens per row** | Empty | Sets images per shared description row. Empty, invalid, or non-positive values use `2`. | | **Use Bluray images** | Off | Adds selected blu-ray.com cover images when available. | | **Bluray image size** | `250` | Sets those cover-image widths; non-positive values resolve to `250`. | ## Text blocks | Field | Default | Effect | | ----------------------------- | --------------- | --------------------------------------------------------------------------- | | **Episode overview** | Off | Adds episode overview text to the shared Unit3D description when available. | | **Tonemapped header** | Built-in notice | Adds the configured notice when screenshots were tone mapped. | | **Custom description header** | Empty | Prepends custom markup in tracker builders that support the shared header. | | **Screenshot header** | Empty | Adds markup immediately before the screenshot block where supported. | | **Disc menu header** | Empty | Adds markup immediately before the DVD menu-image block where supported. | | **Custom signature** | Empty | Appends custom markup in builders that support the shared signature. | | **Add Bluray link** | Off | Adds the selected blu-ray.com release URL when available. | Header and signature values are tracker markup, commonly BBCode. Preview them before submission; malformed or unsupported markup is not made portable automatically. :::note Compatibility fields **Multi screens**, **Pack thumb size**, **Char limit**, **File limit**, and Description's **Process limit** remain in the schema but have no current runtime reader. ::: ## Verify the change Save, prepare `Example.Release.2026.1080p-GRP`, generate its descriptions, and inspect every tracker tab. Artwork options need matching provider data; an empty result does not necessarily mean the setting failed. --- ## Image Hosting settings Use **Settings → Image Hosting** to define global image-upload candidates. **Host 1** has highest priority; blank and duplicate entries are ignored. Tracker policy can restrict the candidates, and a tracker-specific **Image host** setting can override the global preference. ## Configure host priority Choose up to six hosts in preferred order. The Web UI reveals credential fields only for selected hosts. | Host | Required setting | | ------------ | ------------------------ | | ImgBB | API key | | ImgBox | None | | Pixhost | None | | Lensdump | API key | | PTScreens | API key | | OnlyImage | API key | | Dalexni | API key | | Zipline | Base URL and API key | | PassTheImage | API key | | Seedpool CDN | API key | | ShareX | Endpoint URL and API key | | UTPPM | API key | When an allowed host fails, upbrr can try the next eligible configured host. A host rejected by the target tracker's policy is skipped regardless of its global position. ## Additional hosts **Lostimg** and **ReelFliX** are conditional, tracker-owned integrations. Enable one and enter its API key only when a configured tracker advertises support. They are not general global fallback slots. ## Verify the change Save, open **Upload Images**, select test images, and inspect the planned host per tracker before uploading. A successful image upload does not prove every tracker accepts that host; verify the generated description or dry-run preview too. --- ## Settings The Web UI **Settings** page edits runtime configuration and manages related security state. Open **Settings**, choose a section, make the change, then select **Save**. ## Configuration actions | Action | Result | | ---------- | ----------------------------------------------------------------------------------------------- | | **Reload** | Reloads persisted configuration and discards unsaved edits. | | **Export** | Downloads the current configuration with secrets kept encrypted. | | **Import** | Replaces persisted settings with an imported Python, YAML, or JSON configuration after warning. | | **Save** | Validates, persists, and activates all unsaved configuration edits. | Invalid configuration is rejected without replacing the active runtime. If an environment variable overrides a field, the stored value can save successfully while the environment value remains active. :::warning Before importing Export the current configuration first. Import replaces the configuration stored in the database and cannot be undone from the Web UI. ::: ## Secrets and direct actions Stored credentials appear as `[REDACTED]`. Leave that value unchanged to preserve the secret, enter a new value to replace it, or clear it to remove it. Never include configuration exports, API tokens, cookies, passkeys, or announce URLs in public reports. Most sections stage edits until **Save**. These sections behave differently: - **Application Details** is read-only. - **API Tokens** creates and revokes tokens immediately. - **Tracker Auth** imports, checks, and deletes auth state immediately. Use **Show advanced** only when a section offers it. Advanced fields are active settings unless their reference page identifies a compatibility-only field. ## Sections | Section | Purpose | | ----------------------------------------------- | ---------------------------------------------------------------- | | [Main](./main.md) | Metadata access, browser history, icons, and scene detection. | | [Image Hosting](./image-hosting.md) | Ordered upload hosts, credentials, and conditional hosts. | | [Metadata](./metadata.md) | Discovery, tracker-data, image, and Blu-ray lookup policy. | | [Screens](./screens.md) | Screenshot generation, upload concurrency, and tone mapping. | | [Description](./description.md) | Shared description layout, headers, artwork, and signatures. | | [Arr](./arr.md) | Sonarr and Radarr metadata enrichment. | | [Post Upload](./post-upload.md) | Client-injection delay and tracker upload concurrency. | | [Trackers](./trackers.md) | Enabled trackers, defaults, credentials, and tracker options. | | [Torrent Clients](./torrent-clients.md) | qBittorrent, qui proxy, watch-folder, linking, and path mapping. | | [Client Handling](./client-handling.md) | Default, search, and injection client selection. | | [Torrent Specific](./torrent-specific.md) | Reusable torrent piece preference and rehash scheduling. | | [Application Details](./application-details.md) | Build, platform, FFmpeg, and uptime diagnostics. | | [API Tokens](./api-tokens.md) | Scoped bearer-token creation and revocation. | | [Tracker Auth](./tracker-auth.md) | Encrypted cookies, remote checks, relogin, and 2FA state. | After changing upload behavior or credentials, inspect every tracker preview and run **Dry Run**. Dry Run suppresses tracker submission but still attempts client injection by default; select **Skip client injection** when no torrent should be added. For CLI testing, combine `--debug` with `--no-seed` (`-ns`). Logging configuration and the live viewer are on the separate [Logging page](../logging.md). --- ## Main settings Use **Settings → Main** for application-wide metadata and Web UI presentation controls. | Field | Default | Effect | | --------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- | | **TMDB API** | Empty | Enables TMDB lookups and enrichment. Other providers and supplied IDs remain available when empty. | | **Input history limit** | `20` | Caps source paths retained in each browser. `0` disables and clears retained history; negative values are rejected. | | **DB path** | Runtime-selected | Shows the active SQLite path. Saving cannot move the running instance; choose the database path when starting upbrr. | | **Use favicons** | On | Fetches and displays tracker icons on supported workflow pages. | | **Favicon only** | Off | Hides tracker names where an icon is shown. Has no effect when **Use favicons** is off. | | **Scene detection (srrdb)** | On | Enables SRRDB scene detection during preparation. Turning it off prevents those SRRDB requests. | TMDB API is a secret. The Web UI masks a saved key; leaving `[REDACTED]` unchanged preserves it. :::note Compatibility fields **Update notification**, **Verbose notification**, and **Tracker pass checks** remain in the imported/exported schema but have no current runtime reader. ::: ## Verify the change Save, prepare a synthetic release such as `Example.Release.2026.1080p-GRP`, then inspect its metadata. Tracker icon changes appear across Input, Tracker Data, Dupe Check, and Descriptions without restarting the server. --- ## Metadata settings Use **Settings → Metadata** to control how preparation gathers reusable torrent and tracker metadata. | Field | Default | Effect | | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------ | | **Skip auto torrent** | Off | Skips automated torrent-client searching during preparation. | | **Skip tracker filename lookup** | Off | Prevents filename-based tracker-data lookup when no tracker ID is already known. | | **Use largest playlist** | Off | Lets unattended CLI preparation choose the largest Blu-ray playlist instead of requiring confirmation. | | **Get Bluray info** | Off | Enables blu-ray.com matching for BDMV or DVD sources with an IMDb ID. | | **Bluray score** | `94.5` | Sets the normal blu-ray.com candidate score threshold. | | **Bluray single score** | `89.5` | Sets the threshold used when only one candidate is available. | ## Advanced compatibility fields - **BTN API** is a legacy location. Current configuration migrates it to the BTN entry under [Trackers](./trackers.md). - **Keep images**, **Only ID**, **User overrides**, **Ping Unit3D**, and **Check Predb** remain in the stored schema but have no current runtime reader. Similarly named per-release options can still affect an individual preparation. ## Verify the change Save, prepare a synthetic release, then inspect **Tracker Data** and the preparation progress. Blu-ray lookup requires a disc source and IMDb identity; an ordinary video file will not exercise those settings. --- ## Post Upload settings Use **Settings → Post Upload** for timing and concurrency around tracker submission and torrent-client injection. | Field | Default | Effect | | --------------------------- | ------- | ------------------------------------------------------------------------------------------------------- | | **Inject delay** | `0` | Waits this many seconds before each torrent-client injection. A tracker-specific value can override it. | | **Max concurrent trackers** | `4` | Caps simultaneous tracker uploads. `0` uses the built-in limit of `4`; negative values are rejected. | Set a tracker-specific **Inject delay** under [Trackers](./trackers.md) when only one tracker needs extra time before client injection. :::note Compatibility fields **Show upload duration**, **Print tracker messages**, **Print tracker links**, **Search requests**, **Cross seeding**, and **Cross seed check everything** remain in the schema but have no current runtime reader. ::: ## Verify the change Save and use **Dry Run** to validate tracker preparation. Dry Run suppresses tracker submission but still attempts torrent-client injection by default. Select **Skip client injection** when no torrent should be added; for CLI testing, combine `--debug` with `--no-seed` (`-ns`). Use a controlled approved upload when real submission concurrency must be verified. --- ## Screens settings Use **Settings → Screens** for generated screenshots, automatic DVD menu captures, and image-upload concurrency. | Field | Default | Effect | | -------------------------------- | ------- | ----------------------------------------------------------------------------------------------- | | **Screens** | `4` | Number of screenshots requested during automatic generation. Must be greater than zero. | | **Maximum DVD menu images** | `6` | Caps automatic distinct DVD menu captures. Accepted range is `0`–`32`; `0` resolves to `6`. | | **Min successful image uploads** | `3` | Accepts a partially failed host batch after this many images publish. `0` requires every image. | | **Frame overlay** | Off | Adds frame number, frame type, and a tone-mapped HDR marker when applicable. | | **Overlay text size** | `18` | Sets overlay text size relative to a 1080-line frame. | | **Tone map** | On | Tone maps HDR captures for display. | | **Use libplacebo** | Off | Tries Vulkan/libplacebo tone mapping when tone mapping is on and frame overlay is off. | ## Advanced fields | Field | Default | Effect | | -------------------------- | -------- | ----------------------------------------------------------------------------- | | **Process limit** | `2` | Caps concurrent FFmpeg screenshot processes when **FFmpeg limit** is enabled. | | **Max concurrent uploads** | `6` | Caps concurrent image uploads; values at or below zero resolve to one worker. | | **FFmpeg limit** | Off | Enables the process limit. | | **FFmpeg compression** | `6` | Sets PNG compression level; accepted range is `0`–`9`. | | **Tonemap algorithm** | `mobius` | Selects the software FFmpeg tone-map algorithm. | | **Desat** | `10.0` | Passes the desaturation value to the software tone-map filter. | **Cutoff screens** remains in the schema but has no current runtime reader. ## Verify the change Save, open **Screenshots**, generate a small set, and inspect output before uploading. Libplacebo retries and falls back to the software chain when its capture path fails. --- ## Torrent Clients settings Use **Settings → Torrent Clients** to create named clients. Those names become choices under [Client Handling](./client-handling.md) and tracker-specific **Torrent client** fields. ## Add an entry Select **Add entry**, enter a unique name, then choose its **Type**: - **qBit** connects through a qui proxy URL or directly to qBittorrent WebUI. - **Watch** copies a returned torrent file into a watched folder. ### qBittorrent connection Choose one connection method per entry: | Field | Purpose | | ---------------------------- | -------------------------------------------------------------------------------------------------- | | **Qui proxy URL** | Base URL for a qui-backed qBittorrent proxy. A nonblank value takes precedence over direct fields. | | **qBit direct** | Shows or clears the direct qBittorrent connection fields. | | **qBit URL / port** | Direct qBittorrent WebUI address. `http://` is added when the scheme is omitted. | | **qBit user / pass** | Required for a direct connection. | | **Verify WebUI certificate** | Verifies HTTPS certificates. Keep enabled unless a trusted self-signed setup requires otherwise. | To switch from qui proxy to direct qBittorrent, clear **Qui proxy URL**, enable **qBit direct**, and fill the direct fields. Turning **qBit direct** off clears both direct and proxy connection fields. Stored proxy URLs and credentials are encrypted in configuration transport and appear as `[REDACTED]` in the Web UI. ### Watch folder **Watch folder** is required and must be writable by the upbrr process. URL-only tracker results cannot be delivered to a watch folder because no torrent file exists to copy. **Storage directory** remains visible for configuration compatibility but has no current runtime reader. ## qBittorrent add options | Field | Effect | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | **qBit category** | Category for normal injections. | | **qBit tag** | Comma-separated tag value for normal injections. | | **qBit cross category/tag** | Overrides category or tag for torrents marked as cross-seeds. | | **Use tracker as tag** | Uses the tracker name only when no configured tag applies. | | **Automatic management paths** | Enables qBittorrent automatic management when the original local save path is under a listed root and linking is not used. | ## Link staging and path mapping **Linking** can stage source files as `hardlink`, `reflink`, or `symlink` before injection. Leave it as **None** for direct source-path injection. | Field | Effect | | ----------------------- | ----------------------------------------------------------------------------------------------------- | | **Linked folder** | One or more roots where per-tracker staged layouts can be created. Required when linking is enabled. | | **Allow link fallback** | Falls back to the original source path when staging or torrent-layout validation cannot be completed. | | **Local path** | upbrr-visible path prefix. Entries pair by position with **Remote path**. | | **Remote path** | Corresponding qBittorrent-visible prefix used for save paths. | Hardlinks require source and destination on the same filesystem. Reflinks require supported storage and same-filesystem cloning. Symlinks require the needed OS permissions and a path qBittorrent can resolve. Turn off fallback when silently using the original path would be unsafe. ## Verify the entry Save, select it under **Searching clients**, and prepare a known source to test read-only discovery. There is no connection-test button. Injection writes or links data, so verify mappings and permissions before the first controlled upload. --- ## Torrent-Specific settings Use **Settings → Torrent Specific** for torrent reuse and rehash scheduling. | Field | Default | Effect | | ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- | | **Prefer max 16 torrent** | Off | During torrent-client search, prefers a validated reusable torrent whose piece size is at most 16 MiB. | | **Rehash cooldown** | `0` | Waits this many seconds after reusable-torrent submissions finish before starting rehash-dependent uploads. | **Prefer max 16 torrent** affects selection among reusable client torrents; it does not impose a piece size on every newly generated torrent. A negative rehash cooldown behaves as zero. :::note Compatibility field **Mkbrr threads** remains in the schema but has no current runtime reader. ::: ## Verify the change Save, prepare a source with known torrents in a configured search client, and inspect the selected reusable torrent. Rehash cooldown is observable only in a real upload plan containing both reusable and rehash-dependent tracker submissions. --- ## Tracker Auth Use **Settings → Tracker Auth** after saving a tracker entry. The page shows only configured trackers whose backend capability requires managed cookies, login, refresh, or 2FA handling. Tracker Auth actions persist immediately and do not use the page-level **Save** button. Static API keys, passkeys, usernames, passwords, and OTP URIs remain under [Trackers](./trackers.md). ## Status | Status | Meaning | | ----------------------- | ------------------------------------------------------------------------- | | **Configured** | Required managed auth is ready. | | **Has cookies** | Encrypted stored cookies are available. | | **Login required** | Current state needs login or renewed cookies. | | **Storage unavailable** | Encrypted cookie storage cannot be used. | | **Error** | Status or remote validation failed; read the displayed sanitized message. | | **Not configured** | No usable managed auth state is stored. | Capability chips show whether the tracker supports cookie import, login, automatic relogin, TOTP, manual 2FA, API keys, or passkeys. They describe backend support; the page renders only actions valid for that tracker. ## Actions | Action | Result | | ------------------ | ---------------------------------------------------------------------------------------------------------------- | | **Import Cookies** | Selects a Netscape `.txt` or JSON cookie file and stores accepted cookies encrypted. Files are limited to 1 MiB. | | **Check Auth** | Performs remote validation when the tracker supports it. | | **Submit 2FA** | Completes an active manual 2FA challenge when the code field appears. | | **Delete Auth** | Deletes stored cookies and tracker-managed auth state; tracker configuration remains. | Automatic relogin uses saved tracker credentials only when the backend capability supports it. Never share cookie files, 2FA codes, challenge details, or auth errors that may contain private tracker information. ## Storage recovery Cookie storage depends on key material beside the active database. Treat `web-auth.json` and `db.sqlite` as sensitive credentials: give both files restrictive permissions, keep them out of shared storage, and never attach them to support requests. Together they can expose encrypted cookies and other stored secrets. Back up and move them together; replacing or losing `web-auth.json` can make encrypted secrets and cookies unusable. After importing or changing credentials, select **Check Auth** where available. To verify tracker preparation without submission or client injection, select **Skip client injection** before running **Dry Run**. --- ## Trackers settings Use **Settings → Trackers** to enable supported tracker entries and configure only the fields advertised by the current tracker catalog. ## Add a tracker 1. Choose a tracker under **Entries** and select **Add entry**. 2. Open its card and enter the required activation credential, such as an API key, passkey, announce URL, or account credentials. 3. Configure only the upload options you understand. 4. Select **Save**. 5. If the tracker uses managed cookies or login, continue under [Tracker Auth](./tracker-auth.md). Adding an empty card does not make an unusable tracker ready. upbrr determines configured state from tracker-owned activation fields supplied by the backend catalog. ## Defaults and priority | Control | Effect | | --------------------------------- | ----------------------------------------------------------------------------------------------------- | | **Default trackers** | Preselects configured trackers when starting a release. | | **Preferred tracker data source** | Moves that tracker to the front of tracker-data lookup and qBittorrent tracker priority when present. | Defaults do not bypass workflow eligibility, auth, duplicate checks, validation, or manual review. ## Common tracker fields Each tracker shows a different subset. | Field family | Purpose | | --------------------------------------- | -------------------------------------------------------------------------------------------- | | API key, passkey, announce URL | Authenticates tracker API, upload, or announce operations as required by that tracker. | | Username, password, OTP URI | Supports tracker-owned login or automatic relogin. Managed cookie state is shown separately. | | **Anonymous**, **Mod queue**, **Draft** | Sets tracker-specific upload flags where supported. | | **Image host** | Chooses an eligible host for that tracker instead of relying only on global priority. | | **Torrent client** | Overrides global client handling for torrents registered by that tracker. | | **Link dir name** | Names the tracker staging directory when torrent-client linking is enabled. | | **Favicon URL** | Overrides the tracker icon source used by the Web UI. | | **Skip if rehash** | Omits the tracker when preparation must generate new torrent data. | | **Inject delay** | Overrides the global post-upload client-injection delay for that tracker. | Other fields are tracker-owned. Their labels and defaults come from the running backend, not a universal schema. See [Trackers](../../trackers/index.md) for support boundaries. ## Remove a tracker **Remove** resets the entry to catalog defaults, hides its card, and removes its default and preferred-source selections. Select **Save** to persist those changes. Unsupported preserved entries appear separately because no current implementation can use them; delete them only when you no longer need their retained config. Tracker credentials are secrets. Leave `[REDACTED]` unchanged to preserve a value. After any tracker change, check [Tracker Auth](./tracker-auth.md) and run **Dry Run** before submission. --- ## Upload workflow upbrr separates source preparation, tracker decisions, media work, payload review, submission, and post-upload effects. Each stage consumes the exact prepared state approved by earlier stages. ## 1. Select the source Provide a release folder or file. upbrr resolves the source layout, finds reusable torrent-client data when enabled, and creates a prepared release generation. Folder handling matters. `--keep-folder` preserves a supplied folder instead of processing only a selected video file. ## 2. Review canonical metadata Metadata providers and local media inspection produce shared release facts. Review at least: - title and year; - movie, TV, anime, or other category; - release type, source, and resolution; - season, episode, edition, service, distributor, region, and group; - external IDs; - generated release name. Overrides change the prepared generation. Later operations must use that exact generation rather than silently rebuilding it. ## 3. Resolve tracker names and eligibility Each tracker can project its own upload and duplicate-search names from the reviewed source facts. upbrr resolves those names before duplicate checks so the search evidence and eventual payload refer to the same reviewed identity. Tracker rules and constructibility checks can mark a lane ready, blocked, skipped, or requiring manual review. A tracker-specific block need not stop other eligible trackers. ## 4. Review duplicate evidence Duplicate search results are evidence, not an automatic upload decision. Review candidate names, metadata, and tracker warnings. Where approval is required, select an explicit non-empty tracker subset after the duplicate stage. Never infer trumping, coexistence, or slot capacity from a release name alone. ## 5. Prepare media and descriptions Depending on the source and trackers, upbrr can: - inspect MediaInfo, BDInfo, DVD, or other prepared technical data; - select Blu-ray playlists; - generate screenshots at chosen frames; - capture compatible DVD menus or import disc-menu images; - upload selected images to allowed hosts; - build tracker-specific BBCode descriptions. Inspect image ordering, host URLs, technical blocks, headers, and rendered BBCode. ## 6. Preview immutable tracker operations Tracker preparation captures an immutable operation. Payload preview and live submission use that captured state rather than regenerating names, rereading mutable prepared input, or uploading images again. - **Description preview** prepares only the description. - **Dry run** and upload review can prepare a preview but cannot submit it. - **Upload** consumes the approved operation once. Short-lived remote tokens can still be acquired at submission time when required by a tracker. ## 7. Submit and retain registered torrents After confirmed tracker success, upbrr records the tracker result and attempts to retain the tracker-registered torrent. Client injection consumes that registered artifact, not the pre-upload torrent. A failure to download or persist the registered torrent does not turn a confirmed remote upload into a failed upload. Review the warning and recover the torrent manually when needed. ## 8. Inject into clients Client injection is enabled by default when configured. Disable it explicitly with CLI `--no-seed` or the corresponding Web UI upload option. Check save path, category, tags, automatic management, staging mode, and source-file access. Hardlink, reflink, and symlink staging have filesystem-specific requirements. ## Debug and unattended modes | Mode | Submission | Prompts | Client injection | | ---------------------- | ----------------------------------------- | ------------------------ | -------------------------- | | Normal | allowed after review | allowed | enabled when configured | | `--debug` | suppressed | allowed | enabled unless `--no-seed` | | `--unattended` | allowed when all required decisions exist | never | enabled when configured | | `--unattended_confirm` | allowed when confirmed | required prompts allowed | enabled when configured | Debug mode is not a non-mutating dry run. It can perform screenshots, image uploads, remote searches, tracker preparation, and later workflow effects. Add `--no-seed` when testing without client injection. ## Final review checklist Before submission, verify: - release name matches current tracker rules; - category and type are correct for every tracker; - movie, TV, disc, remux, encode, WEB, HDTV, pack, season, and episode handling are correct; - source, resolution, edition, service, distributor, region, language, tag, and group are correct; - screenshots are valid, ordered, and hosted on allowed hosts; - description BBCode renders correctly; - torrent contents, piece settings, and announce behavior are expected; - client category, tags, save path, and injection target are correct; - duplicate results, rule warnings, and manual prerequisites have been read. When any item is uncertain, stop before upload and resolve it manually.