Server Setup Guide

Definitions of Media Locations

There are two types of drive locations that should be setup: pre-processing and post-processing locations.

Pre-processing locations are folders that Klypp uses before it processes the files that it finds.

Recommended flow: FileSaveLocation → IncompletePath → CompletedPath

• FileSaveLocation - When a file is uploaded from your mobile device, Klypp will save it into this location.
• IncompletePath - A staging folder for in-progress transfers. Point this to where partially written files live so Klypp can wait until they finish.
• CompletedPath - A ready-to-process folder. Once files are complete, place them here so Klypp knows when to start organizing them.

Destination locations: destinations for the files and folders after Klypp has processed them.

• Music - All music is copied to this location. The 4K box is ignored for music.
• TV/TV4K - TV episodes are copied to this location.
• Movie/Movie4K - Movies are copied to this location.
• KidsTV/KidsTV4K - This location, if it is setup, overrides other TV locations for TV shows that are for younger audiences.
• KidsMovie/KidsMovie4K - This location, if it is setup, overrides other Movie locations for movies that are for younger audiences.
• 4K - Video content (movies and TV episodes) can be separated by whether or not the transferred media is 4K. See the advanced setup guide for examples.

Basic Setup

For the most basic setup, add locations for Music, TV, and Movies (all with the 4K box unchecked). With this setup, Klypp will move all movies into the Movies location, all TV episodes into the TV location, and all music into the Music location.

After you map these folders, Klypp Server will monitor CompletedPath and move files into your library automatically.

On Linux or MacOS, you may need to adjust permissions. The service runs under the klypp user to keep access isolated from your personal account.

If you already have TV shows, you can scan existing folders to populate the mobile app — or start fresh with a new folder just for Klypp.

After a scan or a new upload, the mobile app will show your media.

How it Works (Simple, UI-Based)

The basic setup can be extended into a more granular version by adding KidsTV and KidsMovies to the mix. Klypp uses metadata from The Movie Database (TMDB) to determine which movies and shows are for kids, and puts them into their own locations.

To get even more advanced, you can check the 4K box for any of the movie and TV locations. When using the 4K box, it's recommended to also have a location with the 4K box unchecked (ie, one Movies location for non-4K content, and one for 4K content).

And finally, for the most advanced setup, you can split your locations across multiple storage devices. For example, if you have 2 Network Attached Storage (NAS) devices, you can tell Klypp to prioritize one over the other for each location. Klypp is smart enough to detect if you already have a TV show on one of the devices, and it will keep putting new episodes for that show on that device, regardless of the priority order.

To summarize: Klypp routes each media title based on two things:

1. Type you can configure: Movies, KidsMovies, Television, KidsTelevision
2. Whether that location’s 4K checkbox is ON (4K path) or OFF (non-4K path)

There are no special names like “Kids4kMovies.” You simply enable a destination and choose if it’s for 4K or not. You can enable both a non-4K and a 4K path for the same type.

TV: Multiple Drives & Priority (Exact Behavior)

Each TV destination can have several paths, each with a Priority number. The app checks them in order: 1 → 2 → 3 → … → N.

• Colocate if found: As it scans from 1 upward, if it finds the show folder on any drive, it uses that same drive for the new season/episode (keeps the show intact).
• New shows land on the last drive: If the scan reaches the end (N) without finding the show, the app creates the show on drive N (the last/lowest-priority drive).
• Why this matters: You can add new drives (higher numbers) while older lower-number drives fill up. Existing shows keep writing where they already live, and new shows naturally start on the newest “last” drive.
• If you remove a drive from the copy list: The app will write to whatever remains in the 1→N sequence. Doing this mid-series can split a show across drives, so prefer leaving older drives mounted and adding new ones with higher numbers. If you plan to retire a drive, wait until all shows on it have finished airing (or relocate them intentionally) before removing it.

In short: Scan priorities 1..N → if show exists at k, write to k; if not found anywhere, create on N.

Advanced: Direct Uploads (Bypass the Relay)

By default, Klypp uploads can go through the relay so you don’t need to make your server reachable from the public internet. If you prefer to bypass the relay, you can use a private VPN network (like Tailscale, ZeroTier, or WireGuard) to connect your phone to your server using a private network address. This can reduce internet exposure, but security still depends on how your VPN, firewall, devices, and server are configured.

Recommended apps (cross-platform)

• Tailscale (easy setup, device-to-device, works well for direct uploads)
• ZeroTier (similar idea, also cross-platform)
• WireGuard (more manual, great if you want full control)

How it works

• You install the VPN app on both your server and your phone.
• The VPN assigns your server a private IP/hostname that is reachable only by devices on that VPN.
• Klypp uploads go to that private address instead of the relay.

Security tips: If you don’t need your upload service public, avoid opening/forwarding router ports for uploads. Keep your server and VPN clients updated, and use firewall rules to restrict access where possible. Using a private VPN typically keeps the upload address off the open internet, but it’s not a guarantee—review your configuration.

Mobile app: Find Server (VPN IP dropdown)

In the mobile app, go to Settings → Find Server. Klypp will scan and show discovered servers on your network. If you’re connected to a VPN (like Tailscale/ZeroTier), you can select your server’s VPN IP from the dropdown.

Example

If your server’s VPN IP is 100.x.y.z, for example, your upload endpoint could be:
http://100.x.y.z:8081/api/upload
(If your server supports HTTPS, prefer https://.)