Automating AI provider configuration after environment variable deprecation

[electriquo]

Some AI provider environment variables are marked as deprecated, with guidance to configure providers via the Settings UI instead:

Deprecated: The following AI provider API key environment variables are deprecated. Configure providers via the Settings UI instead. These variables may still work as a fallback but are no longer recommended.

However, environment variables are still a common and practical way to configure containers with AI providers, especially in automated or reproducible deployments (e.g., Docker, CI/CD).

This raises a gap in the current guidance: how should users automate provider configuration without relying on deprecated environment variables?

For example:

• What is the recommended approach for configuring a TTS endpoint in automated environments?
• How should OPENAI_COMPATIBLE_BASE_URL_TTS be set (or replaced) in a non-interactive setup?

It would be helpful to clarify:

• Whether there is (or will be) a supported non-UI configuration mechanism (e.g., config files, API, or new environment variables)
• What the best practice is for containerized or headless deployments

Without this, it's unclear how to reconcile the deprecation with common automation workflows.

Relates to #558

[lfnovo]

Moving this from Q&A to Ideas and keeping it open as the canonical product Discussion for unattended provider configuration in Docker, CI/CD, headless, and infrastructure-as-code deployments.

The concern is valid: interactive credential management is convenient, but reproducible and automated deployments need a supported provisioning contract. The current runtime still contains database-first, environment-variable-fallback behavior, while the documentation inconsistently describes those variables as either supported fallbacks or deprecated. Issue #1135 tracks that immediate documentation decision.

This Discussion should address the broader product contract: supported environment variables, credentials API provisioning, config or secrets files, bootstrap behavior, idempotency, secret rotation, and how automation can avoid exposing keys. Once those decisions are made, documentation or implementation work should be split into Issues.

[electriquo]

hi @lfnovo

.env files were discussed many times in many projects (including this).
why do you think it is not a good for open-notebook?

[electriquo]

hi @lfnovo, would be happy to hear your thoughts about this...

[lfnovo]

@electriquo — sorry for the slow reply after your ping.

Direct answer: .env isn't bad — it's the wrong source of truth for this product. The main reason is the ordinary user running Open Notebook locally: safely managing API keys in environment variables, and restarting containers to change them, is exactly the friction we want to remove for that person. Key management lives in the UI first, and that decision shapes the rest:

• credentials in the DB are encrypted at rest (via OPEN_NOTEBOOK_ENCRYPTION_KEY); env vars sit in plaintext in compose files and process environments;
• credentials can be added, fixed, or rotated at runtime, without restarts;
• multiple credentials per provider are supported — something a single OPENAI_API_KEY can't express.

On the current state, you're right that it's inconsistent: env vars still work as a live fallback in the code (model_discovery.py, credentials_service.py), while the docs call them deprecated in one place and recommended in another. So, on record: the env fallback is deprecated — it works today, but there is no guarantee it keeps working. Don't build new automation on it. #1135 will align the docs with this.

For automated deployments — what this Discussion is canonical for — the direction we're leaning: a declarative provisioning tool. A YAML/JSON file describing providers and credentials, plus an idempotent script that applies it through the same credentials API/service layer the UI uses — so encryption, validation and multi-credential come for free. It runs in an init container or CI step; the DB stays the source of truth afterwards; key rotation is re-running it with the new key.

What would validate (or kill) this for your setup:

• Does a provisioning step in your pipeline serve your flow, or do you specifically need env as a live source of truth (change the var → config changes on restart)?
• Do you rotate keys through the pipeline, and how often?
• What input would you want — a file in the repo, secrets injected at runtime, both?

Status: exploring — env fallback deprecated as stated; declarative provisioning script as the proposed direction; your answers shape whether it graduates to a work item.

[electriquo]

Sorry for the slow reply after your ping.

No need to apologize. THANK YOU for your amazing work! :)

A declarative provisioning tool. A YAML/JSON file...

That sounds good enough to me, and it would be lovely if a YAML/JSON schema were shipped with it.

Does a provisioning step in your pipeline serve your flow, or do you specifically need env as a live source of truth (change the var → config changes on restart)?

.env files pair nicely with Compose files and DotEnv. Since I'm working with containers, and .env has such broad adoption, it feels like a natural fit. Another advantage is that .env files can be interpolated with external environment variables, whereas YAML and JSON don't natively support string interpolation.

That said, I don't necessarily see JSON/YAML as being better than .env for this use case, especially since .env can also be handled through the same credentials API/service layer that the UI uses.

Does a provisioning step in your pipeline serve your flow, or do you specifically need env as a live source of truth (change the var → config changes on restart)?

I assume a provisioning step will serve me well. I don't specifically need an .env file; it just feels like the most natural fit alongside a Compose file.

Do you rotate keys through the pipeline, and how often?

The pipeline runs on demand to provision a unique instance of Open-Notebook, with all credentials unique to that instance. The credentials are randomly generated and rotated at high frequency.

What input would you want — a file in the repo, secrets injected at runtime, both?

I can adapt to either approach. :)

[lfnovo]

Your answers settle the direction. Recording it here rather than opening a work item yet — this Discussion stays the home until we schedule it.

What your reply changed in the design:

• Env interpolation is in. The file describes structure (providers, credentials, base URLs); secrets come in as ${OPENAI_API_KEY}-style references resolved from the environment. So .env + dotenvx + Compose keep working exactly as you use them today — the file replaces the runtime fallback as the supported contract.
• A JSON Schema ships with it, so editors validate the file and you can lint it in CI.
• Idempotent apply by name. Your profile — fresh instance per run, random credentials, rotated often — is the strongest case for it: rotation is re-running the apply with new values; nothing else changes.
• It runs against the service layer, so it works before the API is up (init container, same moment as migrations).

Timing: no date. The shape of the file depends on how provider configuration settles (#947 is the design thread for that), and we'd rather ship it once than twice. #1135 aligns the docs with the deprecated fallback in the meantime. If anyone wants to prototype against the spec above before we schedule it, this thread is the place to say so — and when it ships, you'll be the first test I ask for.

Status: incubating — direction decided, scheduling open; this Discussion remains the canonical home.