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), `createConfig` (creating new configurations), `proxy` (built-in proxy), `service` (built-in usenet engine), `sabnzbd` (SABnzbd-compatible API), `webdav` (the WebDAV share), or `none` for login-only. Users not listed default to `admin`. An entry written before `createConfig` existed no longer allows creating configurations; add it explicitly. e.g. `alice=admin,bob=proxy\|service\|createConfig`.

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).
`CONFIG_SESSIONS_ENABLED`	Config Sessions Enabled	boolean	`true`	Lets someone stay signed in to their configuration after closing the tab, using a cookie the browser cannot read rather than a stored password. Turn it off to require the UUID and password every time.
`CONFIG_SESSION_TTL_SECONDS`	Config Session TTL Seconds	duration	`2592000`	How long a remembered sign-in survives without being used. Every use pushes it forward again. Defaults to 30 days (30d).
`CONFIG_SESSION_MAX_TTL_SECONDS`	Config Session Max TTL Seconds	duration	`7776000`	Hard cap on a remembered sign-in, counted from when it was created and never extended by use. Defaults to 90 days (90d).
`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	`["loopback","linklocal","uniquelocal"]`	Comma-separated list of trusted IPs, CIDR ranges, or the named ranges loopback, linklocal and uniquelocal (the default trusts any proxy on the same host or a private network). Forwarded headers (X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host) are only honoured from these addresses, which decides the requesting IP used for rate limiting and whether session cookies are marked Secure. User IP is always trusted via headers regardless of this setting.
`MAX_JSON_BODY_SIZE`	Max Json Body Size	size	`262144`	Largest JSON request body the API accepts, which bounds saved configurations and uploaded templates. Raise it if large templates are refused with a 413. (restart required)

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
`AIOSTREAMS_OIDC_ENABLED`	Enabled	boolean	`false`	Allow operators to sign in with an OpenID Connect provider. This governs dashboard and config-page access only; it does not affect Stremio addon URLs.
`AIOSTREAMS_OIDC_ISSUER`	Issuer	string	—	OIDC issuer URL. Discovery is performed against {issuer}/.well-known/openid-configuration. Copy it exactly as your provider states it, including any trailing slash. Register <BASE_URL>/api/v1/auth/oidc/callback as an allowed redirect URI with your provider.
`AIOSTREAMS_OIDC_CLIENT_ID`	Client ID	string	—	OAuth client ID issued by your provider.
`AIOSTREAMS_OIDC_CLIENT_SECRET`	Client Secret	string	(unset)	OAuth client secret issued by your provider. (secret)
`AIOSTREAMS_OIDC_SCOPES`	Scopes	list	`["openid","profile","email"]`	Scopes requested at login. Add the scope that carries group membership (often `groups`) if your provider requires one; Google and Entra ID reject an unknown `groups` scope.
`AIOSTREAMS_OIDC_USERNAME_CLAIM`	Username Claim	string	`preferred_username`	Claim used as the AIOStreams username. Use `sub` if your provider lets users rename themselves, since a renamed user otherwise splits their audit history.
`AIOSTREAMS_OIDC_LINK_BY_USERNAME`	Link By Username	boolean	`false`	Treat an SSO identity whose username matches an AIOSTREAMS_AUTH user as that user, rather than refusing the login. Such a session takes its permissions from AIOSTREAMS_AUTH_PERMISSIONS and the group mapping is not consulted, so the person is configured once rather than per login method. Only enable this if you control who can authenticate at your provider and who can change their own username there.
`AIOSTREAMS_OIDC_USERNAME_PREFIX`	Username Prefix	string	—	Prepended to every SSO username. Set to something like `sso:` to make collisions with local AIOSTREAMS_AUTH users impossible.
`AIOSTREAMS_OIDC_GROUPS_CLAIM`	Groups Claim	string	`groups`	Claim carrying group membership. If absent from the ID token, the userinfo endpoint is consulted automatically.
`AIOSTREAMS_OIDC_GROUP_PERMISSIONS`	Group Permissions	map	—	Maps groups to permissions. Comma-separated `group=perm\|perm` entries (valid: admin, proxy, service, sabnzbd, webdav, createConfig, none). Group names containing "," or "=" (such as LDAP DNs) must use the JSON object form instead, e.g. {"cn=admins,ou=groups,dc=example,dc=com":"admin"}.
`AIOSTREAMS_OIDC_DEFAULT_PERMISSIONS`	Default Permissions	string	—	Permissions for an SSO user whose groups match nothing above. Empty means such a user is refused, which is the safe default. Set to `admin` only if every user your provider admits should administer this instance.
`AIOSTREAMS_OIDC_ALLOW_LOCAL_LOGIN`	Allow Local Login	boolean	`true`	Keep the AIOSTREAMS_AUTH username/password form available alongside SSO. Turning this off means a provider outage locks everyone out; recover with AIOSTREAMS_OIDC_ENABLED=false and a restart.
`AIOSTREAMS_OIDC_BUTTON_LABEL`	Button Label	string	`Sign in with SSO`	Text on the SSO button on the login page.
`AIOSTREAMS_OIDC_AUTO_REDIRECT`	Auto Redirect	boolean	`false`	Skip the login page and go straight to the provider. Visit `/login?local=1` to reach the password form anyway.
`AIOSTREAMS_OIDC_ALLOW_INSECURE_REQUESTS`	Allow Insecure Requests	boolean	`false`	Permit a plain-http issuer URL. This exposes the client secret and tokens on the wire; use only on a trusted network.

Environment Variable	UI Setting	Type	Default	Description
`FEATURED_TEMPLATE_IDS`	Featured Ids	list	—	Up to 2 template IDs featured on the about page. The first is also the one offered during first-time setup. 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 Variables