Your library,
under your control.

Overview

A personal cinema, not somebody else’s cloud.

Kino Server turns movies and TV shows you have legally acquired into a private streaming catalog. Your source files remain on storage you choose. The Server organizes them, stores catalog data and artwork, authenticates your household, and sends compatible media to Kinotron clients.

Architecture

How Kino works.

Catalog and playback

1. The scanner inventories enabled movie and TV folders.
2. Kino probes technical media details and matches catalog metadata.
3. The Server stores the resulting catalog in its managed PostgreSQL database.
4. A signed-in client asks the Server for a title. Kino selects direct play, remuxing, or another compatible delivery path according to the file and device.
5. Watch progress and account state return to your Server so you can continue on another screen.

Kino’s database is the catalog authority. A NAS index agent reports file inventory; it does not become a second media server and does not own accounts, watch state, or catalog metadata.

Before you begin

Requirements.

• An Apple silicon Mac that can remain available while you watch.
• macOS 14 or later.
• Read access from that Mac to every media folder you want Kino to catalog.
• A writable local location for artwork, generated playback data, and other rebuildable Server storage.
• A TMDB read token for movie and television metadata.
• A stable Server address. Use HTTPS before allowing access outside a trusted local network.

Quick start

From download to first title.

1. Install Kino Server

   Download the signed installer, complete the macOS installation, and open Kino Server from Applications.

2. Complete guided setup

   Choose Set Up Kino. The app walks you through media, access, and artwork information, then creates secure Server settings for you.

3. Start and check readiness

   Choose Start Server. Wait until Database, API, and Scanner report ready, then choose Open Kino.

4. Create your owner account

   The first browser to open a fresh Server is offered the one-time local owner-account form.

5. Add libraries

   In Admin → Libraries, add separate movie and TV-show folders beneath your configured media root.

6. Connect your screens

   Use the same Server address and account on your Kinotron clients.

Server setup

Install and configure Kino Server.

1. Install the signed application

Download the latest Apple silicon installer, open it, and follow the macOS prompts. The installer places Kino Server.app in Applications. Server updates replace only the signed application; your configuration, database, media, generated data, and logs stay outside it.

2. Open guided setup

Open Kino Server and choose Set Up Kino. The five-step guide prepares the supported configuration without asking you to edit files or generate secrets:

1. Welcome: review what Kino will prepare on this Mac.
2. Media: choose the readable folder that contains your movie and TV folders. A stable mount such as /Volumes/Media can contain separate Movies and TV Shows folders.
3. Access: use the suggested address for this Mac and your home network, or enter an existing web address beginning with http:// or https://.
4. Artwork: paste the API Read Access Token from your TMDB account. Kino uses it for posters, descriptions, cast information, and discovery.
5. Finish: review the choices and choose Start Kino.

3. Let Kino start

Kino creates private 256-bit sign-in keys, writes its protected settings, initializes its managed PostgreSQL database, validates the immutable payload, and starts the API and scanner. The status card should show Database, API, and Scanner as running. Open Kino opens the selected address.

Closing the window leaves the Server running. Quitting Kino Server stops its child processes cleanly. The application registers itself to start at login so it can resume after the Mac signs in.

4. Create the first owner

Open Kino. When no users exist, the sign-in page becomes a one-time owner-account setup. Create a strong password. After the first account exists, this bootstrap route closes automatically.

Review or change setup later

Choose Review Setup… in the Server window or Settings. Kino preserves existing secrets while updating your media location, access address, or TMDB token. Its settings, managed database, generated media, backups, and logs live below ~/Library/Application Support/Kino and remain separate from application updates.

Your catalog

Add your libraries.

Open Admin → Libraries → Add library. Each library represents one content kind and one folder beneath MEDIA_ROOT.

1. Give the library a recognizable Name.
2. Choose Movies or TV shows.
3. Use Browse to select the folder. Kino stores a relative path below the media root.
4. Choose a Fallback scan schedule. It is used only when no storage-local index agent owns that library.
5. Leave Apple media derivatives at Analyze only unless you understand and want the optional preparation modes.
6. Save, then watch the library’s scanner state in Admin → Operations.

Movie and TV organization

Keep movie folders separate from TV folders. Clear filenames, season folders, and episode numbers improve matching. Files excluded through a library’s inventory-exclusion settings remain outside the catalog.

Rescanning

Normal watchers and periodic reconciliation keep enabled libraries current. Use the Admin rescan control when you need to request a fresh walk. A large first scan may take time because Kino also probes media and retrieves metadata.

Daily operation

Use the Server app.

Health versus readiness

Health proves the API process is alive. Readiness is stricter: it checks the database, media root, writable storage, required media tools, and scanner heartbeat. A healthy but not-ready Server should not be treated as available for normal use.

curl --fail --silent --show-error http://localhost:3001/api/health
curl --fail --silent --show-error http://localhost:3001/api/ready

Household access

Accounts and clients.

The first local account is the Server owner and administrator. Add household users in Admin → Users, where you can control roles and restrict a user to selected libraries. Keep at least one enabled local administrator as recovery access.

Each client needs the exact Server address and a valid account. When pairing or signing in fails, first open the same address in a browser on that device. This separates a Server or TLS problem from a client-specific problem.

Maintenance

Keep Kino Server current.

Choose Kino Server → Check for Updates… from the application menu or menu-bar item. Routine releases arrive through a signed HTTPS Sparkle feed. The update replaces the application, not the private data below ~/Library/Application Support/Kino.

1. Create or verify a recent backup.
2. Install the offered signed update.
3. Wait for the app to return to Ready.
4. Open Kino and play a known title before considering the update complete.

Protection

Backups and recovery.

In the Server window, choose Configure Backups…. Select a destination, retention policy, schedule, and recovery passphrase. Scheduled backups require the passphrase to be stored in this Mac’s Keychain.

A Kino backup is a verified, encrypted .kinobackup bundle containing the database archive, catalog, manifest, and configuration copy. It does not duplicate your source movie and TV files; protect those through your storage system’s own backup strategy.

• Keep the backup destination on different storage from the Server database.
• Store the recovery passphrase somewhere independent of the Server Mac.
• Use Restore… to rehearse a selected backup before changing the active Server.
• Periodically verify both the Kino backup and the separate media backup.

If you lose administrator access but the Server configuration and database remain intact, use Recover Local Administrator… from the Server window.

Network and security

Publish the Server safely.

On a trusted local network, an explicit local address can be useful while setting up. For remote access, use a stable DNS name and TLS certificate through a reverse proxy. Set PUBLIC_BASE_URL to the address users actually enter.

• Keep port 3001 private; publish only the HTTPS proxy.
• Forward WebSocket and normal HTTP traffic to Kino without rewriting API paths.
• Trust only the exact reverse-proxy socket address or narrowest possible CIDR.
• Do not enable proxy location headers unless the trusted proxy removes caller-supplied values and replaces them with authenticated evidence.
• Keep the Server Mac, reverse proxy, and NAS on supported security updates.

Large network libraries

Storage-local NAS indexers.

A NAS index agent is an optional, authenticated Docker service that runs beside the media. It inventories files locally, persists a small SQLite index, and sends compact snapshots and ordered changes to Kino Server. This avoids repeated recursive directory walks over SMB or AFP.

What the agent does

• Watches one or more exact library roots for changes.
• Persists path, size, modification time, and ordered deltas in SQLite.
• Runs a periodic local audit to repair events missed during downtime.
• Authenticates every /v1 request with a long bearer token.
• Can prepare source-bound cue, subtitle, and explicitly enabled Apple-media artifacts locally.

What it does not do

• It does not own users, metadata, watch state, or the Kino catalog.
• It does not expose private paths from its public health endpoint.
• It does not silently make Kino walk the whole network share if the helper is unavailable.
• It never overwrites an original media file. Optional derivatives are new sibling files and are disabled until you select a derivative mode.

NAS deployment

Set up an indexer on Synology.

1. Mount the NAS on the Server Mac

   Make every library available at a stable path such as /Volumes/MediaNAS. Add those libraries to Kino before generating agent setup.

2. Add the agent in Kino

   Open Admin → Libraries. Under Storage index agents, choose Add agent.

3. Map the two path prefixes

   Enter a name, the agent URL such as http://nas-address:8099, the Kino mount prefix such as /Volumes/MediaNAS, the matching NAS prefix such as /volume1/Media, and a persistent state directory such as /volume1/docker/kino-index-agent.

4. Generate setup

   Choose Generate setup. Copy the complete Compose immediately; the bearer token is displayed once.

5. Create the Synology project

   Ensure the state directory exists. Open Container Manager → Project → Create, name the project, paste the generated Compose, and build it.

6. Wait for healthy, then verify

   Wait for the container health state to become healthy. Return to the agent in Kino Admin and choose Verify. Verification checks both the token and every expected root.

The generated deployment publishes port 8099, stores its SQLite database in the state directory, uses a read-only container filesystem, drops Linux capabilities, enables no-new-privileges, rotates logs, and applies a 1 GiB hard memory limit with a 256 MiB reservation.

Indexer lifecycle

Snapshots, changes, and audits.

First initialization

The first local audit walks each configured root and builds a compact snapshot. Kino preserves its existing catalog while a root initializes. Large libraries can take time; Admin shows the active audit’s item and folder counts.

Normal changes

After initialization, filesystem events become ordered deltas. Kino consumes those changes using a cursor. If a consumer falls too far behind the retained change history, it requests a fresh snapshot rather than guessing.

Periodic repair

By default, the agent runs an audit every six hours. The audit reconciles the SQLite inventory with disk state and repairs anything missed while the container or NAS was unavailable.

Provider failure

If the helper is unreachable or degraded, Kino reports that provider state and preserves the catalog. It does not silently fall back to a recursive network scan, because that could overload the network or mistake a mount outage for mass deletion.

Indexer maintenance

Update or remap an indexer.

1. Open the agent in Admin → Libraries.
2. Choose Save and rotate token.
3. Copy the complete replacement Compose.
4. Replace the Synology Project Compose and redeploy it.
5. Wait for healthy, then choose Verify.

Token rotation intentionally disconnects the old container. Apply the replacement Compose promptly. When you add a library below an existing agent prefix, regenerate and redeploy so its exact root and UUID are included. Editing a library path removes the stale mapping immediately.

Removing an agent returns its mapped libraries to normal filesystem inventory. Kino does not delete the NAS container or its SQLite state directory; remove those manually only when you are certain they are no longer needed.

Troubleshooting

Start with the first failing layer.

Find the first Server error

Choose Show Logs in Kino Server. Check the error logs in startup order: database, API, then scanner. Resolve the first stable error rather than later failures caused by it. Use Review Setup… when the media location, access address, or metadata token needs correction.

Check a NAS container

In Synology Container Manager, confirm the project is running and the container is healthy. Its logs should identify invalid configuration, unreadable roots, watch exhaustion, or a failed audit without returning private paths through the public health endpoint.

Linux watch capacity

inotify is not inode capacity.

The agent uses one Linux inotify watch for every directory below its roots. Synology’s default can be too low for a large media tree. Linux may report ENOSPC when the watch allowance is exhausted even though the disk has plenty of free bytes and inodes.

Check the active inotify limit

cat /proc/sys/fs/inotify/max_user_watches

The validated setting used during Synology testing is 524288. Apply it on the NAS host, then restart the index-agent container:

/sbin/sysctl -w fs.inotify.max_user_watches=524288

Persist it after a Synology restart

1. Open Control Panel → Task Scheduler.
2. Choose Create → Triggered Task → User-defined script.
3. Run it as root on the Boot-up event.
4. Use this script:

/sbin/sysctl -w fs.inotify.max_user_watches=524288

Check actual disk and inode capacity separately

df -h
df -i

Compatibility and help

NAS support boundary.

Useful information for any support request

• Kino Server version and build from the Installation card.
• Whether local health and readiness return successfully.
• The first relevant error, with credentials and private hostnames removed.
• Whether the problem affects one title, one library, one client, or the whole Server.
• For NAS issues: model, CPU architecture, DSM or OS version, container status, and whether the first audit ever completed.