Skip to content

docs: configure AI providers and recommendations from the deployment document - #446

Draft
Quick104 wants to merge 5 commits into
mainfrom
docs/deployment-ai-providers
Draft

Quick104 wants to merge 5 commits into
mainfrom
docs/deployment-ai-providers

Conversation

@Quick104

@Quick104 Quick104 commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Closes #445

The plugin provisioning document is now Silo's deployment document. Besides plugins, it can connect AI providers, and three new variables set up recommendations, so a Compose, Kubernetes, or NixOS deployment can configure AI services without the admin pages. The docs covered only plugins under the old variable names.

Draft until Silo-Server/silo-server#4668 and the pull request it's stacked on, Silo-Server/silo-server#4665, are merged into main. The docs describe #4668, and its labels or defaults may still change in review.

Pages changed

Page Change Preview
Configure Silo from a deployment document (was "Provision plugins from deployment configuration") Retitled; four variable names; new section "Connect AI providers"; releasing providers; examples use SILO_CONFIG_FILE Open
Configure AI services New section "Connect providers from your deployment" Open
Set up recommendations SILO_RECOMMENDATIONS_* variables under "Configure the model"; changing the model when the variables set it Open

What changed on each page

Configure Silo from a deployment document

  • Title is now "Configure Silo from a deployment document". The slug stays docs/provision-plugins, so existing links keep working.
  • "Prepare the declaration": SILO_CONFIG_FILE (YAML or JSON file) and SILO_CONFIG (inline JSON), with "The older names, SILO_PLUGINS_FILE and SILO_PLUGINS, still work and read the same document. Set only one of the four: if two are set, Silo doesn't start." Both plugins and ai_providers are optional, and a section left out leaves those plugins or providers as they are. A short pointer sends AI-only readers to the new section, and the OIDC walkthrough gets its own subheading.
  • New section "Connect AI providers": an example with OpenAI and a custom endpoint, the id rule (1 to 64 lowercase letters, digits, and hyphens, starting with a letter or digit), type values and defaults, api_key only as fromFile or fromEnv (with the four types that need one), capabilities required for custom and refused for the rest, the name-clash stop and its two fixes, replacing a stored provider with the same id and type (a type change stops startup), an example startup error, a pointer to the read-only view on AI Services, and the last-to-start-wins rule. Plugin secrets and AI keys share one 1 MiB secret limit.
  • Compose, Kubernetes, and NixOS examples use SILO_CONFIG_FILE and a deployment.yaml or deployment.json file, and show the AI key's secret next to the OIDC one.
  • "Change settings or hand control back to an administrator": plugins: {} releases every plugin, and leaving the section out releases nothing. New bullet for ai_providers, with the same rules for ai_providers: {} and for leaving the section out, and that removing the document releases nothing; a released provider can be removed once no job uses it.
  • Frontmatter keywords drop the variable names the page now uses in its text and add "config as code" and "infrastructure as code". Questions add "Can I add an AI provider without the admin pages?"

Worth checking: I kept the heading "Prepare the declaration" so its anchor doesn't change.

Configure AI services

  • New section after "Connect speech-to-text" that links to the deployment document. Manage on a declared provider shows it read-only with Set by SILO_CONFIG_FILE in the server’s environment., without Save or Remove, and Test still works. It can still be chosen for Text model or Speech-to-text. To change it or hand it back to administrators, edit the document and restart.

Set up recommendations

  • "Configure the model": SILO_RECOMMENDATIONS_ENABLED, SILO_RECOMMENDATIONS_PROVIDER (the id of a provider the document declares; admin-added providers' ids aren't shown) and SILO_RECOMMENDATIONS_MODEL set Enable Recommendations, Embedding provider, and Model, which then show read-only while Check Connection still works. A second paragraph: they apply on the start that reads them, the startup error for a provider that isn't connected, and the last-to-start-wins rule.
  • "Change the embedding model": change the variables instead when they set the provider and model, including when switching only the provider.

Left out on purpose

Evidence

Source reviewed, not tested on a live server or device:
silo-server de5b0fd907 (Silo-Server/silo-server#4668 with its review fixes), stacked on c7622a0b58 (Silo-Server/silo-server#4665). Docs branch from siloserver.org d3b0482.

The server PR's own evidence shows the read-only provider panel and Recommendations fields on a running server with a declared provider; these pages weren't checked against one separately.

bun run test:docs: tests 8, pass 8, fail 0
bun run build: Complete!
Search: 154 of 164 queries find an expected page in the top 3.
git diff --check: clean

Evidence: https://evidence.siloserver.org/r/siloserver-org/deployment-ai-providers/

Follow-ups

Risks

None identified. Documentation only.

Checklist

  • I read and can explain the complete diff.
  • This pull request addresses one concern.

AI Disclosure

  • Harness: Claude Code in T3 Code
  • Tool(s): Claude Code, GitHub CLI, Bun
  • Model(s): claude-opus-5-5
  • Involvement: Fully AI-generated; a maintainer reviews it before merge
  • Adversarial review: Sol (gpt-6.2-sol), Opus (claude-opus-5-5), Gemini (gemini-4-neon), medium effort, 1 round, 25 of 26 findings applied

🤖 Generated with Claude Code

Quick104 and others added 3 commits November 20, 2026 16:22
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 20, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@silo-triage silo-triage Bot added the size/M 50–199 added + deleted lines (all files); change volume, not priority. label Nov 20, 2026
@silo-kody

silo-kody Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

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 settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌
⚠️ 2 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:

  • Scope polling setup steps to installable source capabilities
  • Preserve retired documentation URLs with tested redirects

@Quick104

Copy link
Copy Markdown
Contributor Author

Draft until Silo-Server/silo-server#4668 and Silo-Server/silo-server#4665, which it's stacked on, are merged into main. The docs describe that change, and its labels or defaults may still change in review.

@silo-triage silo-triage Bot added documentation Improvements or additions to documentation triaged High-confidence review completed; does not mean fixed, validated, or accepted for release. labels Nov 20, 2026

## Connect providers from your deployment

To connect providers from a Compose file, Kubernetes manifest, or NixOS configuration instead, list them under `ai_providers` in the [deployment document](/docs/provision-plugins#connect-ai-providers). A provider the document declares opens read-only under **Providers**, with a note such as **Set by SILO_CONFIG_FILE in the server's environment.** It has no **Save** or **Remove**, and **Test** still works. To change or remove it, edit the document and restart Silo. Under **Models**, choose it for the **Text model** or **Speech-to-text** as you would any other provider.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Bug high

Removing a provider from the document does not disconnect it

The provider remains connected and usable after its document entry is removed. Tell administrators to remove the entry, restart Silo, and then remove the provider under Providers.

Prompt for LLM
File src/content/docs/docs/running-a-server/ai-services.md, line 38:

Removing a provider from the document does not disconnect it

Removing a provider from the document only releases ownership; it remains connected and usable, contrary to the instruction here. Tell administrators to remove the entry, restart Silo, and then remove the provider in the admin pages.

Suggested code:

To change it, edit the document and restart Silo. To remove it, remove its entry from the document, restart Silo, and then remove the provider under **Providers**.

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Preview deployed: https://pr-446.siloserver-org.pages.dev

Commit 39b4e62

Docs changes: 15 changes on 3 pages. Each link opens the first change on its page. Step through the rest with the changes box in the corner of the preview.

Page Changes
Set up recommendations 3
Configure Silo from a deployment document 11
Configure AI services 1

The alias updates after a successful build and deployment. The preview is removed when this pull request closes.

- A declaration keeps a connected provider's type, replaces it whole,
  and shares the document's secret limit with plugin secrets.
- State the id rule and that custom providers need capabilities, and
  use a generic host in the custom example.
- Show the AI key's secret in the Compose, Kubernetes and NixOS steps.
- Keep the read-only provider description on AI Services, say that
  removing the document releases nothing, and how to remove a released
  provider.
- Split the recommendations variables paragraph, say where to set them
  and which provider ids work, and cover switching a provider the
  environment sets.
- Keywords: drop words the page already uses.
@silo-kody

silo-kody Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

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 settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌
⚠️ 2 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:

  • Scope polling setup steps to installable source capabilities
  • Preserve retired documentation URLs with tested redirects

@silo-kody

silo-kody Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

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 settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌
⚠️ 2 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:

  • Scope polling setup steps to installable source capabilities
  • Preserve retired documentation URLs with tested redirects

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/M 50–199 added + deleted lines (all files); change volume, not priority. triaged High-confidence review completed; does not mean fixed, validated, or accepted for release.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: AI providers and recommendations from the deployment document

1 participant