Environment Variables

Environment variables are mainly for Docker and other installs without a window. Desktop users normally set the same values in Settings; environment variables are an alternative, not the default.

Where they're read from The desktop app reads them from your shell environment and from optional .env and .env.local files in its data folder. Docker images read them from the container environment, usually set in docker-compose.yml.

Core app variables

Variable	Default	Description
`METATANA_DATA_DIR`	`/app/data` in Docker	Folder for app state: database, database backups, logs. The desktop app sets it to its own `data` folder; to move that, set `METATANA_ELECTRON_USER_DATA_DIR` to another app folder. See file layout for each platform's default.
`METATANA_DB_PATH`	`$METATANA_DATA_DIR/metatana.db`	Full path to the SQLite database file. Set it only if you want the database outside the data folder.
`PORT`	`3000`	Web server port.
`HOSTNAME`	`0.0.0.0`	Address the web server listens on. `127.0.0.1` allows this computer only.
`NODE_ENV`	`production`	Standard Node setting. Leave it as `production`.
`METATANA_SCAN_CONCURRENCY`	`8`	How many files a scan identifies and reads media info for at once, from 1 to 32. Lower it if scans slow down a small NAS.
`METATANA_SCRAPE_SESSION_CHUNK_SIZE`	`10`	How many titles a large scrape session sends to providers per batch, from 1 to 100.
`METATANA_SCRAPE_SESSION_CONCURRENCY`	`1`	How many of those batches run at once, from 1 to 4.
`METATANA_FFMPEG_PATH`, `METATANA_FFPROBE_PATH`	`ffmpeg`, `ffprobe` from `PATH`	Use a specific FFmpeg or FFprobe program. The Windows app sets these to its own copies.

Docker and NAS runtime

These variables control how the container starts. Leave Docker's User field or Compose user: unset so the container can prepare /app/data and then switch to the user below.

Variable	Default	Description
`PUID`	`1001`	Numeric user ID used by the app process after startup. Unraid shares normally use `99`.
`PGID`	`1001`	Numeric group ID used by the app process after startup. Unraid shares normally use `100`.
`METATANA_BOOTSTRAP_TOKEN`	`(unset)`	Unlocks a new Docker or NAS install. Set it to any long value and restart, then paste the same value into Unlock this server on first run. Treat it as a secret.
`METATANA_RUNTIME_ROLE`	`unified`	`unified` runs everything in one container. A split setup sets `web` on one container and `background` on the other. See deployment modes.
`BACKGROUND_HEALTH_PORT`	`3001`	Port of the background health check (`/health`) that the image's healthcheck calls.
`MEDIA_DIRS`	`/media`	Kept for older compose files. It does not add or scan folders.
`METATANA_ALLOWED_HOSTS`	`(unset)`	Needed only if you open MetaTana through your own domain name, for example behind a reverse proxy or Cloudflare Tunnel. Comma-separated host names, such as `metatana.example.com,nas.tail1234.ts.net`. Without it, those names get `421 Misdirected Request`. See the notes below the table.
`METATANA_APP_BASE_URL`	`(unset)`	The address you open MetaTana at, when it is not `localhost` on MetaTana's own port: Docker on a changed port (for example `http://nas:8080`), a LAN name, or a reverse proxy. MetaTana uses it to recognize links to its own artwork, and the MCP bridge uses it as the app address when `METATANA_MCP_BASE_URL` is not set. When the address you opened is not recognized, Settings › General › More › Database shows the exact line to add.

METATANA_ALLOWED_HOSTS

MetaTana answers only on host names it can trust, so a page on another site cannot reach it through your browser by pointing its own domain at your server (DNS rebinding).

Always allowed: IP addresses (IPv4 and IPv6, any port), localhost and *.localhost, the computer's own host name (inside Docker, the container's), one-word names such as nas, and names ending in .local, .lan, .home, .home.arpa, .internal, or .localdomain.
Format: host names only, comma-separated. No https:// or path. A port is ignored.
Wildcards: *.example.com allows every subdomain of a domain you own, but not example.com itself. List exact names for shared domains where other people can create names, such as *.ts.net, *.synology.me, or dynamic-DNS domains.
* turns the check off and brings back the DNS-rebinding risk. Avoid it.
Restart MetaTana after changing it. In a split setup, set it on the web container.
Your reverse proxy should pass the original Host header (plain nginx: proxy_set_header Host $http_host;, Apache: ProxyPreserveHost On). If the proxy replaces Host with the backend address, pages still load, and changes such as sign-in are accepted only when the browser marks the request as coming from the same page origin and the name you opened MetaTana with is allowed: an IP address, a local name, or a name in METATANA_ALLOWED_HOSTS. Anything else gets 403.

Examples per proxy: Your Own Domain Or Reverse Proxy.

Provider keys

Pro includes hosted metadata, so these keys are optional on Pro. On Free you need your own TMDb key, licensed for your use; you can scan first and add it later. The usual place for keys is Settings › Providers › Your keys, which also tests each one. Environment variables are an alternative for Docker, and Settings shows whether each key works either way.

Variable	Default	Description
`TMDB_API_KEY`	`(unset)`	The Movie Database API v3 credential issued to you and licensed for your use.
`TVDB_API_KEY`	`(unset)`	TheTVDB API v4 key. Sign up at thetvdb.com.
`OMDB_API_KEY`	`(unset)`	OMDb / IMDb mirror key.
`FANART_TV_API_KEY`	`(unset)`	Fanart.tv API key for clearart, logos, disc art.
`MDBLIST_API_KEY`	`(unset)`	MDBList API key for aggregated ratings.
`MYANIMELIST_CLIENT_ID`	`(unset)`	MyAnimeList client ID for anime identity.
`TRAKT_CLIENT_ID`	`(unset)`	Trakt OAuth client ID for sync.
`TRAKT_CLIENT_SECRET`	`(unset)`	Trakt OAuth client secret. Optional: only Trakt apps made before October 2026 have one.
`OPENSUBTITLES_API_KEY`	`(unset)`	OpenSubtitles API key for subtitle search.
`SUBDL_API_KEY`	`(unset)`	SubDL API key for subtitle search.
`ANTHROPIC_API_KEY`	`(unset)`	Your own Anthropic key for AI Insights (Pro). Same as Settings › Providers › AI keys.
`OPENROUTER_API_KEY`	`(unset)`	Your own OpenRouter key for AI Insights (Pro), instead of Anthropic.

Each provider key variable also accepts a _FILE form that points at a file holding the key, for example TMDB_API_KEY_FILE=/run/secrets/tmdb_api_key with Docker secrets. The file wins over the plain variable, and a key saved in Settings › Providers › Your keys wins over both. If the file exists but MetaTana can't read it, Settings says so under that key. See Provider Keys And Secret Files.

API, CLI, and MCP (Pro)

Variable	Default	Description
`METATANA_API_KEY`	`(unset)`	Local API key that the MCP bridge uses instead of the one saved in the app. Find the app's key in Settings › Maintenance › Advanced › API key.
`METATANA_HOSTED_SESSION_TOKEN`	`(unset)`	Pro session token that the MCP bridge and the `metatana` command-line tool use when no signed-in desktop session is available. It also lets a Docker install that nobody opens in a browser confirm Pro by itself, so hooks, webhooks, and hosted metadata keep working. Set it on the background container in a split setup (both containers is fine). `METATANA_HOSTED_SESSION_TOKEN_FILE` works too and wins over the plain variable. Treat it as a secret.
`METATANA_MCP_BASE_URL`	Found automatically	Address of the running app for the MCP bridge. The desktop app's setup finds it on its own; set it only to point the bridge somewhere else, such as a Docker install.
`METATANA_MCP_AI_CREDIT_LIMIT`	`20`	Most AI credits one MCP session may spend on AI identify and metadata translation. `0` turns those calls off; an invalid value uses 20. Set it in the MCP client's `env`. See AI and agents.
`WEBHOOK_URLS`	`(unset)`	Comma-separated webhook addresses used when none are saved in Settings › Maintenance › Advanced › Webhooks. Pro only, like saved webhooks.

Secrets in env vars METATANA_API_KEY, METATANA_HOSTED_SESSION_TOKEN, METATANA_BOOTSTRAP_TOKEN, and provider *_API_KEY values are secrets. Don't paste them into screenshots, public docs, support reports, or commits. Use a .env file with restricted permissions, _FILE secret files, or a secret manager.

Hosted account (advanced)

These point the app at a different hosted API, for development. Release desktop and Docker builds always use the production hosted API for Pro checks, hosted metadata, and hosted AI, so leave them alone.

Variable	Default	Description
`METATANA_API_BASE_URL`	`https://api.metatana.com`	Hosted API address the app's server uses for Pro checks, hosted metadata, hosted AI identify, and metadata translation.
`NEXT_PUBLIC_METATANA_API_BASE_URL`	`https://api.metatana.com`	Hosted API address the browser uses, for sign-in.
`METATANA_MCP_HOSTED_API_BASE_URL`	`https://api.metatana.com`	Hosted API address the MCP bridge uses to check Pro.

Test / dev only

Variable	Default	Description
`METATANA_ENABLE_LOCAL_BOOTSTRAP`	`(unset)`	Lets first run unlock without a bootstrap token when the browser is on the same computer. For development.
`METATANA_E2E_PORT`	`3300`	Port the stable e2e runner binds to.
`METATANA_E2E_HEALTH_TIMEOUT_MS`	`120000`	Health-probe timeout for the stable e2e runner.

No auth-bypass escape hatch in production Release desktop and Docker builds ignore the dev-only auth-bypass variables (METATANA_AUTH_BYPASS and METATANA_TEST_AUTH_BYPASS). The Pro check can't be turned off in a release build.

Going deeper

Reference: API keys: managing keys in Settings
Reference: CLI: uses METATANA_HOSTED_SESSION_TOKEN for the Pro check
Reference: file layout: where METATANA_DATA_DIR actually lives per platform
Docker deployment: typical compose file with env vars set

Environment Variables#

Core app variables#

Docker and NAS runtime#

METATANA_ALLOWED_HOSTS#

Provider keys#

API, CLI, and MCP (Pro)#

Hosted account (advanced)#

Test / dev only#

Going deeper#