Configuration

Almost everything is in the app, under Settings. Environment variables exist only for the handful of things the container cannot work out for itself.

Nothing here is required. A docker run with no -e flags and no --env-file is a complete configuration.

In the app

Account

Change your password. Requires the current one; minimum 12 characters.

Transfers

Setting	Default	What it does
Reroute failed uploads	on	When a drive stops accepting uploads, move the job to another healthy one instead of failing it
Reroute attempts per job	3	Cap on automatic reroutes. Stops one job walking every drive you own when the real fault is the file
Failures before a drive is unhealthy	3	Consecutive upload failures on one drive before it stops being offered
Concurrent transfers	10	Restart required. How many torrents run at once

Concurrent transfers is the one to understand. A download occupies a worker for its entire transfer, so this is a hard ceiling: with it set to 10, the eleventh torrent waits, however idle the machine looks. Raise it if you have bandwidth and disk to spare; lower it on a small VPS.

Changes to the others take effect within about 30 seconds, with no restart.

Downloads

Delete downloads after upload (on by default) removes a job's local directory once every file has reached your cloud storage. Turn it off to keep local copies — they then only go away when you purge.

Local Storage

Shows what the downloads volume holds, split three ways:

Purgeable — directories for completed and cancelled jobs. What Purge deletes.
Retained — jobs still running, retrying or failed. Kept, because those jobs may still need the files.
Orphaned — directories with no matching job. Counted so the space is visible, never deleted automatically.

Purge only ever removes the purgeable set.

Environment variables

None of these are required. A docker run with no -e flags and no --env-file is a complete configuration — the container generates what it needs on first boot.

This table is generated from the backend's own option declarations and attached to each release, so it describes what the code implements rather than what someone remembered to write down. It used to be maintained by hand here, in two READMEs, in deploy/docs and in .env.example, and no two copies agreed.

Generated from TorrenClou 1.1.1, describing 22 configuration values.

Required by the application

These have no built-in default. The all-in-one image generates both on first boot and keeps them on the torrencloud-pgdata volume, which is why you never set them by hand — but a split deployment, where nothing generates them, must supply them.

Variable	Default	What it does
`JWT_SECRET`secretrequired	generated on first run and kept on the postgres volume	Key used to sign API tokens. Rotating it invalidates every session.
`POSTGRES_PASSWORD`secretrequired	password generated on first run; database torrenclo, user torrenclo_user	Assembled by the entrypoint from POSTGRES_DB, POSTGRES_USER and POSTGRES_PASSWORD.

Optional overrides

Setting one overrides the built-in behaviour for that value only.

Variable	Default	What it does
`ALLOW_SCHEMA_AHEAD`	false	Start even when the database has migrations this build does not know about. Only safe if the newer migration is additive and this code never touches what it added.
`APPLY_MIGRATIONS`	true	Run pending database migrations at startup.
`ASPNETCORE_ENVIRONMENT`	Production	Standard ASP.NET Core environment name.
`FRONTEND_URL`	derived from the incoming request	Public address used to build the Google Drive OAuth return URL.
`HANGFIRE_WORKER_COUNT`	10	How many torrents transfer at once. A download holds a worker for its whole transfer, so this is a hard ceiling. The value saved in the Settings tab wins once you save one.
`JWT_AUDIENCE`	TorrenClou_Client	Audience claim written into tokens and checked on validation.
`JWT_ISSUER`	TorrenClou_API	Issuer claim written into tokens and checked on validation.
`OBSERVABILITY_ENABLE_LOGGING`	true	Emit OpenTelemetry logs.
`OBSERVABILITY_ENABLE_PROMETHEUS`	true	Expose the /metrics endpoint. Overridden by the Settings tab once saved.
`OBSERVABILITY_ENABLE_TRACING`	true	Emit distributed traces. Overridden by the Settings tab once saved.
`OBSERVABILITY_LOKI_API_KEY`secret	unset	Basic-auth key for a hosted Loki.
`OBSERVABILITY_LOKI_URL`	the bundled Loki, or unset outside the all-in-one image	Push structured logs to this Loki instance.
`OBSERVABILITY_LOKI_USERNAME`	unset	Basic-auth user for a hosted Loki.
`OBSERVABILITY_OTLP_ENDPOINT`	unset	Send traces and metrics to this OTLP collector.
`OBSERVABILITY_OTLP_HEADERS`secret	unset	Headers for the OTLP exporter, URL-encoded. Usually carries an API key.
`Redis__ConnectionString`	127.0.0.1:6379	Redis endpoint. Set directly only in the split topology; the all-in-one image points this at its own bundled Redis and ignores anything you set.
`TORRENT_DOWNLOAD_PATH`	/data/downloads	Where torrents are written before upload. Shared by the torrent worker and both upload workers.

Legacy

Only for installs that predate the first-run wizard.

Variable	Default	What it does
`ADMIN_EMAIL`	unset; use the wizard instead	Legacy admin login. Setting it disables the first-run wizard. Only for installs that predate the first-run wizard. New installs create the account in the browser.
`ADMIN_NAME`	TorrenClou Admin	Display name for the legacy admin account. Only for installs that predate the first-run wizard.
`ADMIN_PASSWORD`secret	unset; use the wizard instead	Legacy admin password. Converted to a stored hash on first successful login. Only for installs that predate the first-run wizard.

Precedence

For the three settings that exist in both places — worker count and the two observability toggles — the order is:

The value saved in Settings, read at container start
The environment variable
The built-in default

So once you save a worker count in the app, HANGFIRE_WORKER_COUNT no longer has any effect.

Using a .env file

You do not need one. If you would rather keep overrides in a file:

docker run -d --env-file .env ... ghcr.io/torrenclou/torrentclou:latest

.env.example lists the available overrides, all commented out.

Configuration

On this page