You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(config): declare AI providers and recommendations in the deployment - #4668
Related issue: N/A
Discussion: #4653 (AI providers and recommendations from deployment configuration)
Validation tasks: none
Other clients: Apple N/A (no AI admin screens); Android N/A (no AI admin screens); Roku N/A (no AI admin screens)
Stacked on #4665, which adds the stored settings this builds on; review that one first.
A deployment kept in Compose, Kubernetes or NixOS files can install plugins from a document (#4602) and set most server settings from variables, but AI providers and recommendations still needed the web admin. The provider registry holds random ids and encrypted keys, so a variable per setting can't express it.
Approach
One deployment document. The plugin provisioning document becomes Silo's deployment document:
SILO_CONFIG_FILE (YAML or JSON) or SILO_CONFIG (JSON) names it. SILO_PLUGINS_FILE and SILO_PLUGINS keep working for the same document; startup stops when more than one of the four is set.
plugins becomes optional. A document without it leaves plugin installations alone, and the plugin writer starts only when the section is present. plugins: {} still releases them.
The schema keeps apiVersion: 1 and adds an optional ai_providers section.
ai_providers. Each entry is keyed by the provider id the bindings use:
name and base_url default to the type's, as when an admin connects one. capabilities applies only to custom, and a known type that declares it is refused. api_key takes only fromFile or fromEnv; the key is read only on servers that store providers, so a frontend server needs no AI keys.
Each API server stores the declared providers when it starts, inside the transaction that stores the environment's settings (applyEnvSettings). The bindings then validate against the registry they will see. A declared provider replaces the stored one with its id, key included, and is marked with the document's variable (managed_by). A provider an earlier document declared that this one leaves out is released: it stays connected and becomes editable. ai_providers: {} releases them all, and a document without the section leaves the registry alone.
A declared name another provider already has stops startup with an error naming both ids.
Admin. The provider view gains managed_by_env_var, and update and delete of a declared provider return 422managed_by_environment with how to release it. The AI Services panel shows a declared provider read-only with the usual "Set by SILO_CONFIG_FILE in the server's environment." note, without Save, Remove or the new-key hint.
Recommendations. New stored variables SILO_RECOMMENDATIONS_ENABLED, SILO_RECOMMENDATIONS_PROVIDER and SILO_RECOMMENDATIONS_MODEL set recommendations.enabled, .embedding_provider_id and .embedding_model. They are stored before the engine loads its settings, so the embedding jobs can run on the first start. The Recommendations page and the setup wizard's features step show them read-only.
Validation
Go: build, gofmt, go vet, make lint-changed, and the config, plugins, handlers, apiv2 and cmd/silo tests pass. contracts/api/v2/openapi.json and the web schema are regenerated. CI runs the full gate.
Web: production build (with the typecheck of tests), eslint, prettier, and the AI services tests pass.
New tests:
the document reader: the four variable names, the one-of-four rule, optional sections, ai_providers entries and their key references, and the schema's type list matching the provider types;
applying declared providers: replace by id, release, duplicate and taken names, fixed capabilities;
the startup check binding recommendations to a declared provider;
the admin API refusing update and delete of a declared provider.
Live, before: a dev deployment ran the base branch with the document and the three variables set. It ignored them: no providers, recommendations off.
Live, after:
Both providers were listed as declared by SILO_CONFIG_FILE, the OpenAI key read from its file and stored encrypted.
Recommendations were on and bound to the declared embedding provider and model, read-only.
PATCH and DELETE of a declared provider returned 422.
ai_providers: {} released both, after which PATCH returned 200.
A key written inline in the document stopped startup with a schema error, and the value never reached the log.
Not checked live: two API servers reading different documents, and a frontend server with the document set. Tests cover the startup path each takes.
Surface and build: web admin AI Services and Recommendations pages at desktop and phone widths, and the admin API, at e9caa74a. The review fixes in 461a39f change startup's binding check and the Recommendations page's drafts; the review summary comment links their evidence. Later commits before those change nothing the captures show: internal select values, settings taken over while a page is open, declarations refused for a type change, empty capabilities or a blank key, one secret budget, and removed dead guards.
Risks
Stored for the cluster. Like the stored variables, each API server writes the declared providers when it starts, and the last to start wins. Give every API server the same document.
A declaration takes a provider over. Declaring an id an admin created replaces that provider, key included, and locks it. That is how a deployment adopts one, but an admin's edits to it are gone.
Downgrade and rolling upgrades. A build without this change keeps the providers but drops the managed_by marker the next time it saves the registry, so they become editable there. While such a build still serves traffic during a rolling upgrade, an admin save through it drops the marker for every provider until an API server with this change starts again.
A shared SILO_PLUGINS_FILE. A build without this change refuses a document with an ai_providers section and stops at startup. Add the section once every server that reads the file runs this build, and take it out before rolling back.
Restore. A restore into another deployment clears the AI provider registry but leaves the bindings that named its providers, which predates this change. Startup no longer stops on them, since it checks only bindings the environment sets or that name a declared provider, but a declared provider with an id the backup also used would pick its binding up. A separate fix makes the restore clear those bindings too.
Bindings. Only the embedding binding has variables. Text and speech-to-text models are still chosen in the admin, and can point at a declared provider.
Round 1 fixed: a declaration changing a stored provider's type (now refused, as the admin API does); a provider taken over mid-edit showing the draft; capabilities: [] and keys of only whitespace accepted; AI keys counted against a budget of their own; the provider selects' add/none values colliding with chosen ids (also from Codex and CodeRabbit); dead guards; and a test for the admin API's lock. Answered: a legacy-converted "Ollama" provider's name blocking an unnamed ollama declaration (startup names both ways out); a rolling model change (same window on main, since recommendations.* need a restart); AI settings stored before a plugin entry is refused (same order as the env settings on main).
Round 2 fixed (de5b0fd): the ChatGPT plan's select value colliding with a provider declared as chatgpt (all three members); a provider panel or the Recommendations page keeping edits to settings the deployment took over while open; a name-clash error suggesting takeover of a provider of another type; the type-change error now asking for a new name too.
Visual review: 2 rounds, captures from e9caa74a
Member
Round 1
Round 2
Sol
better, 7/10
better, 8/10
Opus
better, 7/10
better, 8/10
Gemini
better, 6/10
better, 8.5/10
Round 1 fixed: the "Editing" status on a locked provider, Serves chips that looked clickable, and the lock note reading as part of the name field. Answered (shared components, same on main): disabled switch, select and placeholder contrast, the note's wrapping, provider rows and the panel indent at phone width, the job cards, the Manage label and the Embeddings row's link, and the field help text.
AI Disclosure
Harness: Claude Code in T3 Code
Tool(s): Claude Code subagents, Codex and Antigravity (council members), Playwright (headless Chromium), GitHub CLI
Model(s): claude-opus-5-5 (implementation, code review), claude-sonnet-5-5 (code-review cleanup finder and validation check), gpt-6.2-sol and gemini-4-neon (plan and visual review)
Involvement: Fully AI-generated, directed by the maintainer; not yet human-reviewed
Adversarial review:
Plan round (Sol, Opus, Gemini) chose one document over new variables, made a missing section leave things alone and {} release them, applied providers in the settings transaction so bindings validate, and cut the text and speech bindings.
Code review at xhigh, run as three finders and a validation check, then a sweep. Fixed: keys read only where providers are stored, a duplicate declared name, a name another provider holds, capabilities on known types, the schema's type list, error wording, and the locked panel's hints.
Add AI provider and recommendations declaration to the deployment config
Deployment documents (read from SILO_CONFIG/SILO_CONFIG_FILE, or legacy SILO_PLUGINS/SILO_PLUGINS_FILE) can now declare an ai_providers section. ReadProvisionDocument in provision_document.go resolves API keys from secret references, counting against the same byte budget as plugin secrets, and converts declarations into config.AIProvider values.
config.ApplyDeclaredAIProviders in ai_providers_declared.go applies declarations at startup: it replaces matching provider IDs, rejects name conflicts and type changes, and releases previously managed providers omitted from the declaration.
Declared providers are reported with managed_by_env_var in the admin API. Update and delete on a managed provider return a managed_by_environment validation error (ErrAIProviderManaged) in admin_ai_providers.go. The admin UI shows the management note and disables editing for these providers.
Adds SILO_RECOMMENDATIONS_ENABLED, SILO_RECOMMENDATIONS_PROVIDER, and SILO_RECOMMENDATIONS_MODEL as environment settings; the recommendations admin page and setup wizard show environment-management notes and use server values for managed settings.
The deployment schema no longer requires the plugins property; plugin provisioning starts only when a plugins section is declared.
Risk: skipBindingsOutsideDeclaration in admin_settings_env.go silently drops stored provider bindings that fall outside the declaration; setting multiple document environment variables now returns an error; provider select sentinel values changed to __add__, __none__, and __chatgpt__.
…ment
Thirteen more server settings can be set from environment variables, with
the checks an admin save runs: the nightly backup schedule and contents
(SILO_BACKUP_*), the Discord application (SILO_DISCORD_*), the MDBList key,
the Meilisearch index, the web media origin, the prepared-download budget
and realtime library monitoring. A deployment kept in version control no
longer needs the admin UI for them.
The web admin shows each of these fields read-only with the variable that
sets it, as it does for the existing variables. The Discord card leaves
keys the environment sets out of its saves and its clear action, which the
server would refuse.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…h entry points
The backup before migrations laid every SILO_BACKUP_* value over the
stored settings. A lower SILO_BACKUP_KEEP then rotated nightly copies
away before the migrations had succeeded, under a value startup had not
stored yet. Only SILO_BACKUP_ENABLED decides that backup now; retention
waits for startup.
A migration job (--migrate-only) read no environment settings, so on the
deploy that first sets SILO_BACKUP_ENABLED=true over a stored false it
migrated without a backup. It now reads them for this one value, and an
invalid value elsewhere falls back to the stored settings with a warning
instead of stopping the migration.
Also drop a test that repeated the env table's invalid-value check.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…aves
- The Discord card left env-set keys out of its saves, but a client
secret or bot token typed before the environment took that key over
still went into the batch, and the server refused the whole save. Each
draft now counts only while its key is editable.
- The Search page's Meilisearch index stayed editable when the
sensitive-status read failed, unlike the other three Meilisearch
fields there.
- A migration job read every environment setting for its one use,
SILO_BACKUP_ENABLED, so an invalid unrelated variable dropped that
value. It now reads that variable alone.
- The before-upgrade backup's comment and doc now say it reads
SILO_BACKUP_ENABLED.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A deployment kept in Compose, Kubernetes or NixOS files could set
recommendations only by scripting the admin API after first start: the AI
provider registry is machine-managed and provider ids were random.
The plugin provisioning document is now the deployment document, read from
SILO_CONFIG or SILO_CONFIG_FILE (SILO_PLUGINS and SILO_PLUGINS_FILE still
work). Its plugins section is optional, and a new ai_providers section
declares providers keyed by the id they keep, with keys given as fromFile or
fromEnv references. An API server stores them at start, in the same
transaction as the environment's settings, so SILO_RECOMMENDATIONS_PROVIDER,
SILO_RECOMMENDATIONS_MODEL and SILO_RECOMMENDATIONS_ENABLED can name one and
the recommendation engine starts with them on that start.
A declared provider replaces the stored one with its id; one no longer
declared stays connected and becomes editable again; an empty section
releases them all, and a document without the section leaves them alone.
Admin updates and deletes of a declared provider are refused with
managed_by_environment, and the API reports managed_by_env_var. Web admin
shows declared providers and env-set recommendation fields read-only.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).
File: No configuration file from this repository applied
Commit: Unavailable
Layers: Organization UI
Review profile: CHILL
Plan: Advanced
Run ID: 65b32f49-f8f9-4e99-bbee-9927743e76e0
Commits
Reviewing files that changed from the base of the PR and between de5b0fd and 8982f78.
Files selected for processing: 27
.env.example
cmd/silo/env_settings.go
cmd/silo/main.go
contracts/api/v2/breaking-approvals.json
contracts/api/v2/openapi.json
contracts/plugins/provisioning/v1/embed.go
contracts/plugins/provisioning/v1/schema.json
docs/admin-settings-api.md
internal/api/handlers/admin.go
internal/api/handlers/admin_ai_providers.go
internal/api/handlers/admin_settings_env.go
internal/api/handlers/admin_settings_env_test.go
internal/apiv2/admin_ai_providers.go
internal/apiv2/admin_ai_providers_test.go
internal/config/ai_providers.go
internal/config/ai_providers_declared.go
internal/config/ai_providers_declared_test.go
internal/config/env_settings.go
internal/plugins/provision_document.go
internal/plugins/provision_document_test.go
web/src/api/v2/schema.ts
web/src/pages/AdminRecommendations.tsx
web/src/pages/admin-settings/AIModelField.tsx
web/src/pages/admin-settings/AIProviders.test.tsx
web/src/pages/admin-settings/AIProviders.tsx
web/src/pages/admin-settings/AISettings.tsx
web/src/pages/setup-wizard/steps/FeaturesStep.tsx
Walkthrough
The deployment document now supports AI-provider declarations alongside plugin configuration. Startup applies declarations and environment settings to stored configuration. The API and web interface identify deployment-managed providers and settings and restrict applicable changes.
Changes: Deployment Configuration and Managed Settings
Layer / File(s)
Summary
Deployment document contract and parsing contracts/plugins/provisioning/v1/*, internal/plugins/provision_document.go, internal/plugins/provision_document_test.go, .env.example
The schema and reader support plugin and AI-provider declarations, secret references, and the SILO_CONFIG, SILO_CONFIG_FILE, SILO_PLUGINS, and SILO_PLUGINS_FILE inputs. Tests cover input selection, key resolution, section presence, and schema consistency.
Startup applies declared providers and environment settings, then validates declared settings against the resulting registry. Pre-migration backup handling reads SILO_BACKUP_ENABLED as an override for backup.enabled.
Managed-provider API contract and enforcement docs/admin-settings-api.md, contracts/api/v2/openapi.json, internal/api/handlers/admin_ai_providers.go, internal/apiv2/admin_ai_providers.go, internal/apiv2/admin_ai_providers_test.go
Provider responses expose the declaring environment variable. Update and delete requests for managed providers return a managed_by_environment validation error.
Managed-provider and setting controls web/src/api/v2/schema.ts, web/src/pages/AdminRecommendations.tsx, web/src/pages/admin-settings/*, web/src/pages/admin-backups/BackupSettings.tsx, web/src/components/settings/*, web/src/pages/setup-wizard/steps/FeaturesStep.tsx
The interface identifies managed providers and settings and disables applicable edits and deletion. Recommendation connection checks use server values for managed keys and exclude them from dirty keys.
Silo-Server/silo-server#4665: Adds environment-variable mappings and managed-setting behavior used by this change.
Silo-Server/silo-server#4498: Adds the environment-managed metadata and validation mechanism used by the admin settings.
Silo-Server/silo-server#3107: Adds the recommendation embedding-provider selection that deployment settings configure.
Suggested reviewers:rhainland, blurbery
Merge Risk: Low · previous review de5b0
Declared AI providers are now applied at startup and locked in the API and admin UI. A few admin screens can still show or save stale values for a setting that a deployment takes over while an admin has an unsaved edit. These are minor, recoverable UI issues that are worth fixing but do not block merge.
Security architecture risk: Minimal · up to de5b0
The inspected changes preserve encrypted credential storage, enforce deployment ownership on provider edits and deletion, and apply provider declarations atomically with related settings. No introduced or worsened material security or ownership failure was established.
Retained concerns
No architecture-level concerns identified.
Security review details
Security Blast Radius
inferred — Authority over the deployment document extends to the database-shared provider registry, its stored credentials, and the endpoints used by bound AI jobs. This is deployment-level authority, not a newly exposed unauthenticated configuration input; the inspected provider operations remain classified as acting-administrator operations.
Trust Boundaries and Controls
observed — Provider update and deletion check persisted deployment ownership inside the mutation callback before changes are saved. Generic single-setting and batch-setting writes independently reject direct writes to ai.providers, preventing those inspected paths from bypassing provider ownership enforcement.
observed — Existing connection-check controls also apply to deployment-sourced keys: draft checks reuse a stored key only for the same normalized scheme, host, and port, and the model-listing HTTP client refuses redirects. These controls predate this PR and were not weakened in the inspected comparison.
Resilience and Maintainability Implications
observed — The settings transaction takes a database advisory lock and rolls back on callback failure before commit. This provides a shared serialization and failure-containment boundary for declaration writes and concurrent administrative mutations; runtime interruption and multi-server behavior were not exercised.
Pre-merge checks: 4
Check name
Status
Explanation
Title check
The title "feat(config): declare AI providers and recommendations in the deployment" matches the main change. The changeset adds an optional ai_providers section to the deployment document, applies de…
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Description check
The description is specific to the changeset. It explains that the plugin provisioning document becomes a deployment document that can declare AI providers and recommendation settings. It names the ne…
Full details: Title check
Explanation
The title "feat(config): declare AI providers and recommendations in the deployment" matches the main change. The changeset adds an optional ai_providers section to the deployment document, applies declared providers at startup, and adds SILO_RECOMMENDATIONS_* variables. The title names the primary change from the developer's perspective and is specific enough for a teammate scanning history.
Full details: Description check
Explanation
The description is specific to the changeset. It explains that the plugin provisioning document becomes a deployment document that can declare AI providers and recommendation settings. It names the new variables (SILO_CONFIG, SILO_CONFIG_FILE, SILO_RECOMMENDATIONS_*), the managed_by marker, the 422 managed_by_environment response, the validation performed, the risks (shared document across API servers, downgrade and rolling upgrade behaviour), and the test coverage. This matches the files in the raw summary, including the provisioning schema, applyEnvSettings, the admin handlers, and the web admin pages.
Finishing Touches
Generate unit tests (beta)
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
The provider selects used "add" and "none" as their own choices. An
admin-created provider's id is always <type>-<hex>, but a deployment
document chooses its providers' ids, and both words match the id
pattern. A provider declared as "none" or "add" would have read as no
provider, or opened the add form. The choices now contain underscores,
which no provider id can.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Legacy conversion can prevent a valid deployment from starting, and an old worker can lock a rolling deployment to its previous model. The line comments explain each finding from the pinned source.
The reason will be displayed to describe this comment to others. Learn more.
S1 · P1 — Legacy conversion can make a valid deployment fail to start. Upgrade a pre-registry install with recommendations enabled and no explicit embedding URL, and declare ollama-local: {type: ollama} with SILO_RECOMMENDATIONS_PROVIDER=ollama-local. main.go:1045 runs legacy conversion first. It commits an Ollama provider with a generated ID and advances the registry version. This merge at line 61 then rejects the declared provider's default name, even though the explicit binding would supersede the converted one. A retry fails on the same committed row. Plan the conversion and declaration together in the settings transaction. Honor explicit bindings, reserve declared names when generating legacy entries, and commit the conversion version only after validation succeeds.
The reason will be displayed to describe this comment to others. Learn more.
Not changed. The converted provider holds the name "Ollama", so a declared ollama provider without a name would take a name that's already used. Provider names have to be unique in the registry, and planning both steps in one transaction would still hit that. Startup stops with an error that names the converted provider's id and both fixes: give the declared provider a name of its own, or declare that id to take the converted provider over. The docs PR shows that error and both fixes.
The reason will be displayed to describe this comment to others. Learn more.
S2 · P1 — A replica running the old configuration can lock the new deployment to the old model. Start a rolling change of SILO_RECOMMENDATIONS_MODEL while the database has no embedding lock. The first restarted replica commits the new model. The old replica's worker still has its startup model because the reload hook only rotates credentials for the same endpoint and model (cmd/silo/main.go:3120). If the old replica gets the next embedding job, it can create the lock for the old model (internal/recommendations/embed_backfill.go:735). The new replica then refuses to embed until an operator resets. The saved-config check currently only protects reset. Check the saved configuration when claiming embedding work and fence vector and lock writes if a deployment change makes an in-flight job stale.
The reason will be displayed to describe this comment to others. Learn more.
Not changed here. The recommendations.* settings take effect only after a restart, so an admin's model change followed by a rolling restart has the same window on main: an old server can claim embedding work for the previous model until it restarts. The variables add another way to make that change; they don't add the window.
The reason will be displayed to describe this comment to others. Learn more.
S3 · P2 — A rejected plugin declaration still applies the document's AI settings. Combine an AI provider or recommendation change with a plugin field that passes the document schema and fails its cached manifest schema. The AI settings commit at line 1077 and publish at line 1250. StartOffline can then return a local validation refusal and stop the process at line 2099. TestProvisionWriterRefusesInvalidSavedConfigDB covers that refusal. Other replicas can see the changed registry even though the rolling restart failed. Run the offline plugin validation that can abort startup before committing or announcing the shared AI settings.
The reason will be displayed to describe this comment to others. Learn more.
Not changed. On main, the environment settings are also stored and announced before the plugin declaration is checked against its manifest. The document's AI section follows the same order. Both are applied again on the next start, which by then has the corrected document, so the outcome is the one the operator asked for.
Focus: what the change can drop and still meet the need (AI providers and the three recommendation variables set from deployment files, shown read-only in the admin), plus correctness in passing.
I found no correctness bug. The release path, the 422 refusals, keys read only on primary API servers, and the binding check against the new registry all hold up. NormalizeAIProvider keeps ManagedBy, and the legacy conversion runs before applyEnvSettings, so declared providers land in a registry that is already at the current version.
The six inline comments are all nits. Each removes code without changing behavior:
O1: the "did the declared registry change" check is done twice, and CheckEnvironmentSettings now has only test callers.
O2: the !*migrateOnly guard on the frontend read can't be false there.
O3: resolveAIProviderKey is longer than it needs to be, and its comment claims a shared secret budget it doesn't use.
O4, O5: the locked embedding-model field is guarded in three places where one would do.
O6: three of the four envNote insertions in RecSettingField render for no variable that exists.
The reason will be displayed to describe this comment to others. Learn more.
O1 (nit, simplification). The check for whether the declared registry differs from the stored one is done twice: here (lines 52-58) and in applyEnvSettings (cmd/silo/env_settings.go:73-77, which builds changed). CheckEnvironmentSettings is now a wrapper that only tests call (production calls CheckDeploymentSettings at env_settings.go:68).
Suggested repair: have applyEnvSettings set declared only when the encoded registry differs from current[config.AIProvidersSettingKey]. Then this function copies declared into normalized and appends declaredBy whenever declared is non-empty, and env_settings.go:73-77 becomes maps.Copy(changed, declared). Folding the two functions into one signature also removes the test-only wrapper. Behavior is unchanged: an unchanged registry still skips the binding group, and a changed one is still checked and named in the error.
…n locked
- A declaration that kept a provider's id but changed its type replaced
it in place, so the models bound to it (another type's) went to the
new endpoint. The admin API already refuses a type change; a
declaration now does too, asking for a new id.
- A provider the deployment took over while an admin had edits open
kept showing, and testing, those edits. A locked panel now shows and
tests the stored provider.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Caution
Some comments are outside the diff and can’t be posted inline due to GitHub limitations.
⚠️ Outside diff range comments (1)
Minor · Reserve add and none as AI provider IDs, or stop using them as… · AIProviders.tsx:706-708
web/src/pages/admin-settings/AIProviders.tsx:706-708 Minor · Functional Correctness · Quick win
Reserve add and none as AI provider IDs, or stop using them as select sentinels.
A deployment can declare a provider with ID add or none. The schema (contracts/plugins/provisioning/v1/schema.json:15-18) and NormalizeAIProvider (internal/config/ai_providers.go:285) both accept these IDs. In EmbeddingProviderField, choosing the declared provider sends add to the add-dialog branch and none to the clear branch (web/src/pages/admin-settings/AIProviders.tsx:754-755). The provider cannot be selected as the embedding provider. Its option also shares a value with a sentinel option, so the displayed selection can be ambiguous.
Reject add and none when a declaration is loaded, in the schema and in NormalizeAIProvider. Alternatively, use select values that no provider ID can produce. Either change keeps the select values unambiguous.
Review info
Run configuration
Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: Organization UI
Review profile: CHILL
Plan: Advanced
Run ID: 1e6bb88b-64f5-438e-a065-a0d9b2fe52be
Commits
Reviewing files that changed from the base of the PR and between c7622a0 and 37b1e6b.
Files selected for processing: 24
.env.example
cmd/silo/env_settings.go
cmd/silo/main.go
contracts/api/v2/openapi.json
contracts/plugins/provisioning/v1/embed.go
contracts/plugins/provisioning/v1/schema.json
docs/admin-settings-api.md
internal/api/handlers/admin_ai_providers.go
internal/api/handlers/admin_settings_env.go
internal/api/handlers/admin_settings_env_test.go
internal/apiv2/admin_ai_providers.go
internal/apiv2/admin_ai_providers_test.go
internal/config/ai_providers.go
internal/config/ai_providers_declared.go
internal/config/ai_providers_declared_test.go
internal/config/env_settings.go
internal/plugins/provision_document.go
internal/plugins/provision_document_test.go
web/src/api/v2/schema.ts
web/src/pages/AdminRecommendations.tsx
web/src/pages/admin-settings/AIModelField.tsx
web/src/pages/admin-settings/AIProviders.test.tsx
web/src/pages/admin-settings/AIProviders.tsx
web/src/pages/setup-wizard/steps/FeaturesStep.tsx
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.
- AI keys counted against a 1 MiB budget of their own instead of the
document's one budget its comment described. They now share it, and
a key comes straight from its captured reference, the only form the
schema allows.
- Drop guards nothing can reach: --migrate-only before the frontend
document read, an env-set model commit from a disabled field, and a
repeated suggestion check.
- The Recommendations page shows the variable note only on the toggle,
the one field there a variable sets.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Checked the deployment document parser, schema, atomic settings/provider application, API error mapping, recommendation rows, web surfaces, generated OpenAPI/schema files, docs, and tests against the PR's claims. The core path (one-of-four document variables, lazy key loading on primary API servers only, single-transaction registry + bindings check, release/missing-section behavior, 422 mapping, and web read-only surfaces) matches the code.
Four low-severity issues came up, noted on their lines:
G1 (low):capabilities: [] on a known provider type passes schema validation and is silently overwritten instead of refused.
G2 (low): A whitespace-only api_key secret value on ollama, whisper, or custom silently becomes an empty key instead of failing startup.
G3 (low):DeclaredAIProviders starts a separate 1 MiB byte counter instead of sharing the document's secret budget with plugins.
G4 (low): No unit test exercises AdminHandler.UpdateAIProvider, DeleteAIProvider, or ListAIProviders against a managed provider.
- `capabilities: []` passed the schema and a known type then silently
took its own set; the schema now asks for at least one capability.
- A key file or variable holding only whitespace became no key at all,
which a provider with an optional key accepted without a word; it now
stops startup.
- Test that the admin API lists a declared provider with its variable
and refuses to edit or remove it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On CodeRabbit's note outside the diff (reserve add and none as provider ids): fixed in 0955181 by the second route it suggests. The provider selects' own choices are now __add__ and __none__, values no provider id can match, so a provider declared as add or none selects like any other.
Round 2, covering 37b1e6b..5d3bc97. The dead-guard removals, the shared secret budget, the toggle-only note, minItems: 1 and the blank-key refusal all check out; go test on internal/config, internal/plugins and the new handler test passes at this head. Three new findings below: one low-severity UI bug the select-value fix missed, one error message that sends an operator around in a circle, and one simpler form of the locked-panel fix.
…tings
- The text provider select used "chatgpt" for the ChatGPT plan, so a
provider declared with that id read as the plan. The select's value
is now "__chatgpt__"; the auth mode keeps "chatgpt".
- A provider panel remounts when the deployment takes the provider over
or releases it, so no draft or test result from before carries
across; a locked panel shows the stored provider.
- The Recommendations page ignores a provider or model draft for a key
the environment took over, in what it shows and in Check Connection.
- A name clash suggests taking the other provider over only when it has
the declared type, and the type-change error asks for a new name as
well as a new id, since the released provider keeps its name.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Files skipped from review as they are similar to previous changes: 1
.env.example
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.
#4665 landed as a squash with one more commit (74d5ebe), so its files take
main's version. internal/plugins/provision_document.go keeps main's
provisiondoc reader from #4654 and this branch's four document variables and
ai_providers section.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
silo-triageBot
added
size/XL
500–999 added + deleted lines (all files); change volume, not priority.
and removed
size/XXL
1000–2999 added + deleted lines (all files); change volume, not priority.
labels
Nov 21, 2026
A document that changes the AI provider registry, or a recommendations
variable, made startup check every stored provider binding, so one a restore
into another deployment left naming a removed provider stopped the server,
which an admin can't fix while it's down. Startup now checks the bindings the
environment sets and those naming a provider the document declares; declaring
never removes a provider, so the rest are as valid as before. A text binding
the ChatGPT plan leaves idle is no longer checked against its provider, as
AIProviderUsers already treats it, and the auth mode joins the binding group.
The Recommendations page also replaced a draft for a key only while the
environment set it, so the draft came back, and could be saved on blur, once
the variable was removed. A key the environment sets now takes the server's
value over any draft.
docs/admin-settings-api.md says how declared providers are released.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Review of 640af99 (this branch after merging main). Two findings inline. CodeRabbit's open comment on web/src/pages/AdminRecommendations.tsx also holds: a draft hidden while the environment sets a key comes back once the variable is removed, and leaving the field saves it over the stored value. I'm fixing all three on this branch and will reply in that thread with the commit. A summary comment follows with the rest, including a design question for the maintainers.
Reviewed 640af99, which is this branch after I merged main: #4665 landed as a squash with one more commit (74d5ebe), so its files take main's version, and internal/plugins/provision_document.go keeps main's provisiondoc reader from #4654 under this branch's four document variables. The fixes are in 461a39f, pushed to this branch. 8982f78 then merges main again and drops the 44 approvals #4757 added for its own restore enums. Against main they match nothing, so the contract check refused them on any change to the contract.
Fixed (3):
Startup checked every stored provider binding whenever the document changed the registry or a SILO_RECOMMENDATIONS_* variable was set, so a binding a restore into another deployment left behind stopped the server. It now checks the bindings the environment sets and those naming a provider the document declares.
A text binding the ChatGPT plan leaves idle no longer stops startup.
The Recommendations page no longer brings back, or saves on blur, a draft for a key the environment took over and then released (CodeRabbit's comment).
CodeRabbit's three other open comments, on the Downloads, Discord and MDBList cards, are already fixed on main by 74d5ebe, which this branch now has.
For the maintainers to settle:
The document's scope (maintainer decision). This PR names SILO_CONFIG/SILO_CONFIG_FILE "the deployment document", but main's feat(nodepool): create transcode nodes and their keys from the API servers' configuration #4654 keeps transcode nodes in a separate SILO_TRANSCODE_NODES/SILO_TRANSCODE_NODES_FILE document of the same shape, so a nodes: section put in SILO_CONFIG_FILE fails with invalid deployment declaration at /. The options are to fold nodes into this document (keeping the node variables as aliases, since build 2653 shipped them), to give AI providers a document of their own and leave SILO_PLUGINS plugins-only, or to keep this mix. Both precedents are only days old, so this is the cheapest time to decide.
The locked provider's note (maintainer decision). A provider stays declared until a document's ai_providers section leaves it out, so after the variable is removed the panel still says "Set by SILO_CONFIG_FILE in the server's environment." with no Save or Remove, and nothing in the panel says how to release it. A note worded for a deployment-declared provider would need a new catalog string. The API doc now says how release works.
Order with the restore fix. A declared provider whose id a restored backup also used picks up that backup's binding. A separate fix that makes the restore clear the bindings along with the registry is in progress; it should land with or before this PR.
Answered, unchanged:
The recommendation variables lock a field only on servers that set them, and an open panel learns about a takeover only on its next refetch. That's how every environment-set setting has worked since feat(config): set server settings from environment variables #4498.
Removing the document or its ai_providers section changes nothing, as for plugins and transcode nodes, so a server started without the document doesn't release what another server declared. docs/admin-settings-api.md now says so.
Validated features: the validation board couldn't be read, because the review's gh token lacks the read:project scope. The body's Validation tasks: none is unconfirmed.
Validation: the new cases in TestCheckDeploymentSettingsBindsDeclaredProvider failed at 640af99 and pass at 461a39f. go vet, go test for internal/api/handlers, internal/config, internal/apiv2, internal/plugins and cmd/silo, scripts/lint-changed.sh, the web typecheck, the admin settings web tests and the API contract checks pass. Built binaries against a migrated PostgreSQL holding only a dangling ai.text_provider_id, with SILO_CONFIG declaring one provider: 640af99 exited with the text model provider "openai-1a2b3c" is not connected, and 461a39f started and stored the declared provider. A sandbox couldn't be created at the time, so the web change was checked by type and lint only.
User manual:Silo-Server/siloserver.org#445 and the draft docs PR Silo-Server/siloserver.org#446 cover the document, and the fixes don't change what they describe. The AI services page quotes the locked provider's note, so it follows whatever the second decision above settles.
Apple and Android: the apps have no AI admin screens; nothing to pair.
Council (round 1, 640af99): Sol (gpt-6.2-sol, xhigh) 5/10, Opus (claude-opus-5-5, high) 6.5/10, Gemini (gemini-4-neon, xhigh) 7/10. Gemini's first run stopped on a usage limit, and its retry completed.
Fit: 6/10 · Readiness: 8/10 — conditional (assuming CI is green)
Fit: declaring AI providers and recommendations from deployment files suits people who run Silo from Compose, Kubernetes or NixOS, and it stays optional, with the web admin still the default. What holds it at 6 is new surface: a document section, an API field, three variables and four names for one document. The document is named for the whole deployment while transcode nodes keep their own.
Readiness: the three defects are fixed and shown failing on this branch's previous head. What remains is the scope decision and landing the restore fix first.
#4757 approved its own restore change enums, which main now has, so against
main those approvals match nothing and the contract check refuses them.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.
Reviewing changes in Silo
Include the related issue, expected behavior, and validation steps in the PR description.
For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
Follow this repository's AGENTS.md and CONTRIBUTING.md.
Request another review with @kody start-review in a PR comment.
React with 👍 or 👎 to give feedback on individual suggestions.
Review settingsReview Options
The following review options are enabled or disabled:
Options
Enabled
Bug
✅
Performance
✅
Security
✅
Business Logic
❌
⚠️ 4 Kody Rule(s) were not evaluated
These rules declare that they need repository context beyond this diff, and the review could not retrieve it, so they were not judged on this pull request:
Preserve optional store capabilities through production wrappers
Detach mandatory cleanup from request cancellation and bound its lifetime
Preserve durable media identity and share identity-evidence precedence
Bound decoder throughput trades and share direct-play eligibility
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
enhancementNew feature or requestgoPull requests that update go codejavascriptPull requests that update javascript codepriority: P2Limited scope, workaround exists, or polishsize/XXL1000–2999 added + deleted lines (all files); change volume, not priority.stackedBase is another open PR; merge in stack order named in the body
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Related issue: N/A
Discussion: #4653 (AI providers and recommendations from deployment configuration)
Validation tasks: none
Other clients: Apple N/A (no AI admin screens); Android N/A (no AI admin screens); Roku N/A (no AI admin screens)
Stacked on #4665, which adds the stored settings this builds on; review that one first.
A deployment kept in Compose, Kubernetes or NixOS files can install plugins from a document (#4602) and set most server settings from variables, but AI providers and recommendations still needed the web admin. The provider registry holds random ids and encrypted keys, so a variable per setting can't express it.
Approach
One deployment document. The plugin provisioning document becomes Silo's deployment document:
SILO_CONFIG_FILE(YAML or JSON) orSILO_CONFIG(JSON) names it.SILO_PLUGINS_FILEandSILO_PLUGINSkeep working for the same document; startup stops when more than one of the four is set.pluginsbecomes optional. A document without it leaves plugin installations alone, and the plugin writer starts only when the section is present.plugins: {}still releases them.apiVersion: 1and adds an optionalai_providerssection.ai_providers. Each entry is keyed by the provider id the bindings use:nameandbase_urldefault to the type's, as when an admin connects one.capabilitiesapplies only tocustom, and a known type that declares it is refused.api_keytakes onlyfromFileorfromEnv; the key is read only on servers that store providers, so a frontend server needs no AI keys.applyEnvSettings). The bindings then validate against the registry they will see. A declared provider replaces the stored one with its id, key included, and is marked with the document's variable (managed_by). A provider an earlier document declared that this one leaves out is released: it stays connected and becomes editable.ai_providers: {}releases them all, and a document without the section leaves the registry alone.Admin. The provider view gains
managed_by_env_var, and update and delete of a declared provider return422managed_by_environmentwith how to release it. The AI Services panel shows a declared provider read-only with the usual "Set by SILO_CONFIG_FILE in the server's environment." note, without Save, Remove or the new-key hint.Recommendations. New stored variables
SILO_RECOMMENDATIONS_ENABLED,SILO_RECOMMENDATIONS_PROVIDERandSILO_RECOMMENDATIONS_MODELsetrecommendations.enabled,.embedding_provider_idand.embedding_model. They are stored before the engine loads its settings, so the embedding jobs can run on the first start. The Recommendations page and the setup wizard's features step show them read-only.Validation
gofmt,go vet,make lint-changed, and the config, plugins, handlers, apiv2 and cmd/silo tests pass.contracts/api/v2/openapi.jsonand the web schema are regenerated. CI runs the full gate.ai_providersentries and their key references, and the schema's type list matching the provider types;SILO_CONFIG_FILE, the OpenAI key read from its file and stored encrypted.PATCHandDELETEof a declared provider returned 422.ai_providers: {}released both, after whichPATCHreturned 200.Evidence
Evidence: https://evidence.siloserver.org/r/silo-server/deployment-ai-providers/
Surface and build: web admin AI Services and Recommendations pages at desktop and phone widths, and the admin API, at e9caa74a. The review fixes in 461a39f change startup's binding check and the Recommendations page's drafts; the review summary comment links their evidence. Later commits before those change nothing the captures show: internal select values, settings taken over while a page is open, declarations refused for a type change, empty capabilities or a blank key, one secret budget, and removed dead guards.
Risks
managed_bymarker the next time it saves the registry, so they become editable there. While such a build still serves traffic during a rolling upgrade, an admin save through it drops the marker for every provider until an API server with this change starts again.SILO_PLUGINS_FILE. A build without this change refuses a document with anai_providerssection and stops at startup. Add the section once every server that reads the file runs this build, and take it out before rolling back.User manual: Silo-Server/siloserver.org#445, draft docs PR Silo-Server/siloserver.org#446.
Checklist
Council review
Rounds: 2, last reviewed 5d3bc97
Round 1 fixed: a declaration changing a stored provider's type (now refused, as the admin API does); a provider taken over mid-edit showing the draft;
capabilities: []and keys of only whitespace accepted; AI keys counted against a budget of their own; the provider selects'add/nonevalues colliding with chosen ids (also from Codex and CodeRabbit); dead guards; and a test for the admin API's lock. Answered: a legacy-converted "Ollama" provider's name blocking an unnamed ollama declaration (startup names both ways out); a rolling model change (same window on main, sincerecommendations.*need a restart); AI settings stored before a plugin entry is refused (same order as the env settings on main).Round 2 fixed (de5b0fd): the ChatGPT plan's select value colliding with a provider declared as
chatgpt(all three members); a provider panel or the Recommendations page keeping edits to settings the deployment took over while open; a name-clash error suggesting takeover of a provider of another type; the type-change error now asking for a new name too.Visual review: 2 rounds, captures from e9caa74a
Round 1 fixed: the "Editing" status on a locked provider, Serves chips that looked clickable, and the lock note reading as part of the name field. Answered (shared components, same on main): disabled switch, select and placeholder contrast, the note's wrapping, provider rows and the panel indent at phone width, the job cards, the Manage label and the Embeddings row's link, and the field help text.
AI Disclosure
claude-opus-5-5(implementation, code review),claude-sonnet-5-5(code-review cleanup finder and validation check),gpt-6.2-solandgemini-4-neon(plan and visual review){}release them, applied providers in the settings transaction so bindings validate, and cut the text and speech bindings.🤖 Generated with Claude Code
Note
Add AI provider and recommendations declaration to the deployment config
SILO_CONFIG/SILO_CONFIG_FILE, or legacySILO_PLUGINS/SILO_PLUGINS_FILE) can now declare anai_providerssection.ReadProvisionDocumentin provision_document.go resolves API keys from secret references, counting against the same byte budget as plugin secrets, and converts declarations intoconfig.AIProvidervalues.config.ApplyDeclaredAIProvidersin ai_providers_declared.go applies declarations at startup: it replaces matching provider IDs, rejects name conflicts and type changes, and releases previously managed providers omitted from the declaration.managed_by_env_varin the admin API. Update and delete on a managed provider return amanaged_by_environmentvalidation error (ErrAIProviderManaged) in admin_ai_providers.go. The admin UI shows the management note and disables editing for these providers.SILO_RECOMMENDATIONS_ENABLED,SILO_RECOMMENDATIONS_PROVIDER, andSILO_RECOMMENDATIONS_MODELas environment settings; the recommendations admin page and setup wizard show environment-management notes and use server values for managed settings.pluginsproperty; plugin provisioning starts only when apluginssection is declared.skipBindingsOutsideDeclarationin admin_settings_env.go silently drops stored provider bindings that fall outside the declaration; setting multiple document environment variables now returns an error; provider select sentinel values changed to__add__,__none__, and__chatgpt__.Macroscope summarized 8982f78.