AIOStreams has two kinds of configuration:

Bootstrap variables — read from the environment only, before the database is available. They configure the things needed to start the process (server, database, encryption, operator auth, logging). These must be set as environment variables and cannot be changed in the dashboard.
Runtime settings — everything else. These are stored in the database and are best configured in the dashboard (Settings page) where they can be edited live, validated, and changed without redeploying. Every runtime setting still has a matching environment variable: if that variable is set, it becomes a locked override — the value is forced and the field is shown as read-only in the UI. Leave it unset to manage the setting from the dashboard.

Recommended approach: set only the bootstrap variables in your .env, then configure everything else from the dashboard. The .env.sample intentionally only contains bootstrap variables for this reason. Use environment overrides for runtime settings only when you need to lock a value

Bootstrap Variables (environment-only)

These are validated at startup and cannot be set from the dashboard.

Essential

Variable	Default	Description
`BASE_URL`	—	Required. Public URL of your instance, including protocol (e.g. `https://aiostreams.example.com`).
`SECRET_KEY`	—	Required. 64-character hex string used to encrypt stored configurations. Generate with `openssl rand -hex 32`. Cannot be changed after first run. The legacy alias `SESSION_SECRET` is still accepted for one minor release.
`PORT`	`3000`	Port the server listens on.
`DATABASE_URI`	`sqlite://./data/db.sqlite`	Database connection URI. Supports SQLite and PostgreSQL (`postgres://user:pass@host:port/db`).
`DISK_CACHE_DIR`	`<data folder>/cache`	Directory for the disk-backed caches (usenet segments, grabbed NZBs, torrent metadata). Set this to move the caches off the data folder, e.g. onto faster or non-persistent storage.
`REDIS_URI`	—	Redis URI for shared caching. Recommended for multi-instance deployments; single-container setups can leave this unset.
`REDIS_TIMEOUT`	`5000`	Redis client connect timeout in milliseconds.
`SETTINGS_REFRESH_INTERVAL`	`30`	How often (seconds) each instance polls the DB settings version and reloads runtime config if another instance changed a setting via the dashboard. Keeps multi-instance deployments consistent. Set `0` to disable on single-instance setups.
`INTERNAL_URL`	`http://localhost:${PORT}`	Internal URL used for communication with built-in addons. The default is fine for almost all setups.

SECRET_KEY is required and must be a 64-character hexadecimal string. AIOStreams will refuse to start without it, and changing it after first run makes existing encrypted configurations undecryptable.

Operator Authentication

Variable	Default	Description
`AIOSTREAMS_AUTH`	—	Comma-separated `username:password` pairs defining all valid credentials. e.g. `user1:pass1,user2:pass2`.
`AIOSTREAMS_AUTH_PERMISSIONS`	—	Per-user permissions as comma-separated `username=perm1\|perm2` entries. Valid permissions: `admin` (dashboard + everything), `proxy` (built-in proxy), `service` (built-in usenet engine), `sabnzbd` (SABnzbd-compatible API), or `none` for login-only. Users not listed default to `admin`. e.g. `alice=admin,bob=proxy\|service`.
`AIOSTREAMS_AUTH_CONNECTIONS_LIMIT`	—	Comma-separated `username:limit` connection limits (`0` for unlimited) for the built-in proxy.

Logging

These configure the logger.

Variable	Default	Description
`LOG_BUFFER_MAX_BYTES`	`67108864`	Max bytes of recent log lines kept in memory for the dashboard Logs page.
`LOG_BUFFER_MAX_ENTRIES`	`200000`	Hard cap on recent log lines kept in memory for the dashboard Logs page.

Runtime / Build

Variable	Default	Description
`NODE_ENV`	`production`	`production`, `development`, or `test`.
`SYSTEM_LIFECYCLE_ENABLED`	`false`	Allow the dashboard System page to restart/stop the AIOStreams process.

Runtime Settings

Everything below is stored in the database and editable from the dashboard Settings page. The sections, groups, and labels mirror the dashboard exactly. Set the listed environment variable only if you want to lock that value (it will appear read-only in the UI). Defaults shown are the built-in defaults used when neither the environment variable nor a stored value is present.

Environment Variable	UI Setting	Type	Default	Description
`AIOSTREAMS_AUTH_REQUIRED`	Auth Required	boolean	`false`	When true, /stremio/configure requires a valid login session (any user in AIOSTREAMS_AUTH) and the config-write gate (CONFIG_ACCESS_KEY) is enforced. When false, the config page is public.
`CONFIG_ACCESS_KEY`	Config Access Key	string	(unset)	Single key embedded in a config and checked on create/update/serve. If unset while authRequired is true, one is generated and persisted automatically. Rotating it invalidates every existing config until re-saved. (secret)
`SESSION_TTL_SECONDS`	Session TTL Seconds	duration	`86400`	Lifetime of a login session before the user must log in again. Defaults to 24 hours (1d).
`ALIASED_CONFIGURATIONS`	Aliased Configurations	map	(unset)	Map of aliases to {uuid, password} accessible at /stremio/u/<alias>/manifest.json. Env-supplied form: comma-separated `alias:uuid:password` entries. (secret)
`ENABLE_SEARCH_API`	Enable Search API	boolean	`true`	When true, the /api/v1/search endpoint is mounted and reachable. (restart required)
`ENABLE_NAB_API`	Enable NAB API	boolean	`true`	When true, the per-user /api/v1/newznab/api and /api/v1/torznab/api endpoints are mounted and reachable. These expose a user’s stream results to newznab/torznab clients (Prowlarr, Sonarr, Radarr) as an indexer, supporting ID and season/episode lookups only. (restart required)
`PROVIDE_STREAM_DATA`	Provide Stream Data	boolOrList	—	Whether stream metadata is included in Stremio stream responses. `null` (default) auto-detects from User-Agent (AIOStreams/* always gets it). `true`/`false` overrides for everyone. An IP list enables it only for matching request IPs.
`EXPOSE_USER_COUNT`	Expose User Count	boolean	`false`	Include the total user count on the public status endpoint.
`STREMIO_ADDONS_CONFIG_ISSUER`	Stremio Addons Config Issuer	string	`https://stremio-addons.net`	Issuer URL declared in the manifest for the Stremio Addons Config integration.
`STREMIO_ADDONS_CONFIG_SIGNATURE`	Stremio Addons Config Signature	string	(unset)	Signed JWT for the Stremio Addons Config integration. Both issuer and signature must be set for the manifest field to be emitted. (secret)
`TRUSTED_IPS`	Trusted Ips	list	`["172.17.0.0/16","127.0.0.1/32","::1/128"]`	Comma-separated list of trusted IPs / CIDR ranges. Used when determining the requesting IP. User IP is always trusted via headers regardless of this setting.

Environment Variable	UI Setting	Type	Default	Description
`ADDON_NAME`	Addon Name	string	`AIOStreams`	Display name shown in the manifest and UI.
`ADDON_ID`	Addon ID	string	`com.aiostreams.viren070`	Reverse-DNS identifier published in the manifest. (restart required)
`CUSTOM_HTML`	Custom Html	string	—	Optional HTML injected into the configuration page.
`ALTERNATE_DESIGN`	Alternate Design	boolean	`false`	Switches the frontend to the alternate design (different logo and theme).

Environment Variable	UI Setting	Type	Default	Description
`FEATURED_TEMPLATE_IDS`	Featured Ids	list	—	Up to 2 template IDs featured on the about page. Defaults to the first 2 available templates when unset.
`TEMPLATE_URLS`	Urls	list	—	Remote template URLs to fetch and cache locally. Templates are downloaded once and refreshed on the schedule below.
`TEMPLATE_REFRESH_INTERVAL`	Refresh Interval	duration	`86400`	How often remote templates are refreshed (accepts e.g. "12h", "1d"). Set to 0 to disable automatic refresh.

Environment Variable	UI Setting	Type	Default	Description
`TMDB_ACCESS_TOKEN`	TMDB › Access Token	string	(unset)	TMDB Read Access Token used for strict title matching. (secret)
`TMDB_API_KEY`	TMDB › API Key	string	(unset)	TMDB API key used for strict title matching. (secret)

Environment Variables

On this page