Skip to content

docs: run Silo Server on a Mac, with a VideoToolbox transcode node - #450

Draft
Quick104 wants to merge 7 commits into
mainfrom
docs/mac
Draft

Quick104 wants to merge 7 commits into
mainfrom
docs/mac

Conversation

@Quick104

@Quick104 Quick104 commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Closes #449

The site had no Mac guide. On a Mac, the install guide's /opt/silo data path fails in Docker Desktop with mounts denied, and Silo in Docker converts video on the CPU because Docker's Linux VM can't use VideoToolbox. This adds a Mac guide that covers both.

It documents unmerged server changes, so it stays a draft until they merge:

Pages changed

Page Change Preview
Run Silo Server on a Mac New page Open
Install Silo Server Points Mac readers to the Mac guide Open
Transcode nodes Sends a node on the same Mac as a Docker Desktop server to the Mac guide Open

What changed on each page

Run Silo Server on a Mac

  • New page under Get started, slug: docs/mac.
  • "Install the server": the install guide with Docker Desktop, the Mac values for MEDIA_ROOT, SILO_DATA_ROOT, PUID and PGID, the mounts denied error the guide's /opt/silo gives, and the removable-volume prompt for media on an external drive.
  • "Convert video with the Mac's hardware" (Apple Silicon only): install ffmpeg-full, add the node in Admin > Playback > Nodes with Source access set to Through the API servers, issue its key, copy the node out of the container with docker compose cp, and run ./silo node install --server http://localhost:8090. It covers the key prompt that hides what you paste, keeping the Mac awake, what the installer checks before it changes anything, --port, and the rollback when the node isn't ready within a minute.
  • "Check the node": Healthy, VIDEOTOOLBOX in Acceleration, pinning VideoToolbox in the editor when the cluster setting names another backend, the re-probe button, and a Quality test that shows in the node's Transcodes count.
  • "Update the node" and "Remove the node".
  • keywords: "Mac mini", "MacBook", "iMac", "M1", "M4", "Docker for Mac", "media engine", "LaunchAgent". questions: "Can I host my media server on a Mac mini?", "Why does Silo in Docker on my Mac convert on the CPU?", "How do I use my Mac's media engine for transcoding?", "What does mounts denied for /opt/silo mean?"

Worth checking: the page tells Mac readers to keep TZ and SECRET_KEY from the install guide and changes only the other four .env lines.

Install Silo Server

Transcode nodes

  • "To convert video on the same Apple Silicon Mac that runs your server in Docker Desktop, follow Convert video with the Mac's hardware instead. For a node on another machine, follow the steps below."

Left out on purpose

  • Intel Macs: the node is built only for Apple Silicon, and the page says it needs Apple Silicon.
  • A server run natively on macOS, outside Docker: the page covers Docker Desktop only.
  • Node log rotation and per-node FFmpeg paths: neither is a setting yet.

Evidence

Tested on a live server and device: an Apple M4 Mac mini with the server in Docker Desktop, following the page's steps with the node from silo-server#4950 and the editor from silo-server#4940. Source reviewed at silo-server#4940 58ae25fc0 and silo-server#4950 16e5f217d.

Needs a hands-on check: nothing beyond re-checking labels once the server pull requests merge.

bun run test:docs: tests 8, pass 8, fail 0
bun run build: All internal links are valid.
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/mac-videotoolbox-node/

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, T3 Code delegate tasks, Codex CLI
  • Model(s): claude-opus-5-5
  • Involvement: Fully AI-generated, human verified
  • Adversarial review: Sol (gpt-6.2-sol) and Opus (claude-opus-5-5), 1 round, accepted findings applied; Gemini was unavailable

🤖 Generated with Claude Code

Quick104 and others added 6 commits November 21, 2026 00:18
Covers the Mac values for the install guide's .env, the removable-volume
prompt for media on an external drive, and a transcode node on the same Mac
for VideoToolbox: installing ffmpeg-full, adding the node and its key,
copying the node program out of the server image, and installing, checking,
updating, and removing it.

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>
…her backend

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Lead with the Mac values for .env, the mounts-denied error and the
removable-volume prompt; add what the installer checks before it starts,
how to keep the Mac awake, and how to see a conversion reach the node.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@silo-triage silo-triage Bot added the size/M 50–199 added + deleted lines (all files); change volume, not priority. label Nov 21, 2026
@silo-kody

silo-kody Bot commented Nov 21, 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 ❌

@coderabbitai

coderabbitai Bot commented Nov 21, 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

@Quick104

Copy link
Copy Markdown
Contributor Author

Draft until Silo-Server/silo-server#4950 and Silo-Server/silo-server#4940 are merged into main. The docs describe those changes, and their labels or defaults may still change in review.

@silo-triage silo-triage Bot added the documentation Improvements or additions to documentation label Nov 21, 2026

## Convert video with the Mac's hardware

This needs a Mac with Apple Silicon. Run a transcode node on the Mac itself, outside Docker, to convert video with VideoToolbox, the Mac's video hardware. Docker on a Mac runs Linux in a virtual machine that can't use VideoToolbox, so Silo in Docker converts video on the CPU.

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 Kody Rules high

Mac node instructions present unmerged functionality as available

Readers may expect the Mac node and installer to be available in current server images. Mark the instructions as dependent on the unmerged change in Silo-Server/silo-server#4950.

Also found in:

  • src/content/docs/docs/get-started/mac.md:76-76

Kody rule violation: Qualify playback documentation by implementation availability

Prompt for LLM
File src/content/docs/docs/get-started/mac.md, line 30:

Mac node instructions present unmerged functionality as available

Qualify the Mac node instructions as dependent on the unmerged server change. As written, the page presents the node and installer as available in current server images.

**Also found in:**
- `src/content/docs/docs/get-started/mac.md:76-76`

Kody rule violation: [Qualify playback documentation by implementation availability](https://kodus.siloserver.org/settings/code-review/1247779129/kody-rules/efe5218f-b87c-4b64-81da-675ed3c8c7e7?teamId=ba9922fc-c0ea-4cf8-87bb-9d4f42ffc73e)

Suggested code:

This needs a Mac with Apple Silicon. The Apple Silicon node and its installer are proposed in Silo-Server/silo-server#4950 and are not yet generally available. Once that change is available in your server version, run a transcode node on the Mac itself, outside Docker, to convert video with VideoToolbox, the Mac's video hardware. Docker on a Mac runs Linux in a virtual machine that can't use VideoToolbox, so Silo in Docker converts video on the CPU.

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 21, 2026 •

Copy link
Copy Markdown

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

Commit c2470d3

Docs changes: 4 changes on 4 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
Install Silo Server 1
Requirements and installation options 1
Run Silo Server on a Mac (new page) 1
Add and check transcode nodes 1

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@silo-kody

silo-kody Bot commented Nov 21, 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 node install --server http://localhost:8090
```

`--server` is the address the Mac reaches Silo at: port `8090` from the install guide, or the `PORT` in your `.env`. When the installer asks for the node key, paste it and press Return; the key doesn't appear as you paste it.

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 Kody Rules high

Mac node instructions present unmerged playback changes as available

Users may expect the installer and VideoToolbox node-editor option to work with released server images. Note that they depend on the unmerged changes in Silo-Server/silo-server#4950 and Silo-Server/silo-server#4940, respectively.

Kody rule violation: Qualify playback documentation by implementation availability

Prompt for LLM
File src/content/docs/docs/get-started/mac.md, line 64:

Mac node instructions present unmerged playback changes as available

Qualify the Mac node instructions as dependent on the proposed server changes. The installer and VideoToolbox node-editor option are described as available, but their changes are still unmerged.

Kody rule violation: [Qualify playback documentation by implementation availability](https://kodus.siloserver.org/settings/code-review/1247779129/kody-rules/efe5218f-b87c-4b64-81da-675ed3c8c7e7?teamId=ba9922fc-c0ea-4cf8-87bb-9d4f42ffc73e)

Talk to Kody by mentioning @kody

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

​

​

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.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: run Silo Server on a Mac, with a VideoToolbox transcode node

1 participant