Set up KumoYami from scratch
From your kumoyami.com account to your first film in the Library, step by step and in order.
This guide walks the whole way, in the order that works best: the account, the plan, the install, the wizard, your folders and clouds, access from outside and the people you share with. Each step is short and links to its own page with all the details. Allow about half an hour, plus however long your library takes to scan.
What you'll need
An email address (or a Google, GitHub or Apple account), a machine to install it on (a Linux server, a NAS or a computer with Docker) and, to reach it from outside your home, a domain, a Cloudflare tunnel or Tailscale. See the requirements.
1. Create your kumoyami.com account
Sign in to My account with Google, GitHub, Apple or your email: we send you a one-time link and, once you open it, you're in. There are no passwords to remember.
The first time you sign in, your account is created with a Gratis (free) license, with no card and no expiry. It's the account you'll link your servers to, and where you'll see your licenses, servers, orders and invoices.
2. Choose your plan (Gratis works too)
The Gratis plan already gives you Files and the basic Library, with no limit on storages or accounts. The paid plans add the best of each side:
| Plan | What it's for |
|---|---|
| Gratis | Files and the basic Library, on 1 server. |
| Pass | The best of the Library: your home cinema (GPU, profiles, Watch together, skip intro…). |
| Pro | The best of Files: sharing and creating (upload boxes, albums, Patreon, watermark…). |
| Total | Pass and Pro together. |
Each paid plan is paid monthly, yearly or once, for life. Compare them on Pricing and in Plans and features. You can start on Gratis and upgrade, or change plan or period, whenever you like from My account: the license and your servers stay the same.
3. Install the server
Pick your platform. On all of them, KumoYami listens on port 4890 (the launcher and the panel), plus 4891 (the Library) and 4892 (Files), and keeps everything you set up in its data folder.
Synology: the Package Center package
The native KumoYami Server package runs directly on DSM, without Container Manager: Node.js and ffmpeg come inside, with the Intel graphics drivers to convert video. It needs DSM 7.2 or later on a NAS with a 64-bit Intel or AMD processor; the one for 64-bit ARM models is in beta and converts with the processor only (best with 1 GB of RAM or more). If you'd rather use Docker, you can set it up yourself with Docker Compose in Container Manager, though we prefer the native one. Which one to pick and how to move between them, on the Synology page.
So that updates arrive in Package Center like any other package's, add KumoYami as a package source:
- Package Center → Settings → General → Trust Level: choose Any publisher (the package comes from a third party, not from Synology).
- Package Center → Settings → Package Sources → Add: name
KumoYami, locationhttps://kumoyami.com/synology. - Find

KumoYami Server in Package Center, install it and follow its wizard: the shared
folder for the data, the folder with your content (optional), the port and the time zone.
Every other platform
Linux (server or VPS)
One command: installs Docker if needed, mounts your folders, detects the GPU and sets up access from outside.
Synology
The package or, until it arrives, Container Manager with Docker Compose.
Unraid
With KumoYami's template, from the Docker tab.
QNAP
In Container Station, as a Docker Compose application.
TrueNAS SCALE
As a custom app with a Docker Compose file.
Docker Compose by hand
On any system with Docker.
On a Linux server or VPS, over SSH:
curl -fsSL https://kumoyami.com/install.sh | sudo bashThe image is public: Docker pulls it without docker login and without a license. You link the license afterwards, in
step 4.
On Windows and macOS, with its installer
On your PC or Mac, KumoYami installs like any program, without Docker: get it from Downloads and follow Windows and macOS.
4. The wizard: your access and your license
Open http://MACHINE-IP:4890/admin (or the address the installer gave you). The first time, the setup wizard opens, in
three steps.
The setup code
So that nobody else sets up your server before you do, the wizard asks for a code that KumoYami writes to its logs when it starts. The wizard itself tells you where to look on your platform:
| Where you installed | Where the code is |
|---|---|
| Linux, with the installer | When it finishes, the installer shows the panel password and you skip this step. If you ran it with --no-admin-password, it shows the code. |
| Docker Compose (also QNAP and TrueNAS) | docker compose logs web | grep -i código, or in the container's logs. |
| Synology, native package | File Station → the data shared folder → logs → kumoyami.log. |
| Synology, Container Manager | Container Manager → Container → KumoYami's → Details → Log. |
| Unraid | Docker tab → KumoYami's icon → Logs. |
Look for the line «Código de configuración» (the server writes it in Spanish).
The panel password
Choose the password for /admin (make it a long one) and your site's name. Later you can add a second step with an
authenticator app or passkeys.
Link the server to your account
The wizard shows a short code, such as BCDF-GHJK, and a button that opens
kumoyami.com/en/activate with the code already filled in. Sign in, check the server's name, address and
version, pick the license and confirm. The wizard finishes on its own: there are no keys to copy.
The code lasts 15 minutes; if it runs out, ask for another. On a server with no browser to hand, Tengo una clave de
licencia (I have a license key) lets you paste the key (KY1.…) you'll find in My account.
If you signed in with the installer's password (or with ADMIN_PASSWORD in .env), there's no wizard: the panel opens
the Licencia (License) page, where you link the server the same way, with Vincular con kumoyami.com (Link with
kumoyami.com).
30 days offline
The server confirms its license every hour with licenses.kumoyami.com (an outgoing HTTPS connection). If it loses
internet access, it keeps working for 30 days; once it's back online, it catches up on its own. More in
the setup wizard and the license and Your license.
5. Choose your modules: Library, Files or both
KumoYami has two sides, each on its own address:
- The Library: your films, series, music, books and photos as a streaming service.
- Files: your folders and clouds in a web index, with share links, upload boxes and a network drive.
Coming soon, in the wizard
The wizard will ask what you want to use: the Library, Files or both (at least one). Each will have its default
address, app.yourdomain.com for the Library and drive.yourdomain.com for Files, and you'll be able to change them.
Today, each part is switched on and off in Sistema → Módulos (System → Modules, Modules), and that's also where each module's address goes, once you have a domain (step 7).
Until then, on your network, the server's address (http://MACHINE-IP:4890) opens a launcher with a card for each
module, and each one also has its own port: the Library on 4891 and Files on 4892.
6. Add your storages
In the panel, Almacenamientos → Añadir almacenamiento (Storages → Add storage). You can bring several together in a single index.
Server or NAS folders
Choose Carpeta local (local folder) and its path inside KumoYami (/data/<name>). KumoYami only sees the folders you
give it, with the access you give it: read only is enough to show them and for the Library; to upload, rename or
delete from the web (uploads, upload boxes, file requests) the folder needs read and write.
- Synology, package: Control Panel → Shared Folder → the folder → Edit → Permissions → the System internal
user drop-down →
kumoyami: Read only, or Read/Write for upload folders. KumoYami sees it at once, with no restart (path/volume1/<folder>). - Synology, Container Manager: mount the folder in
docker-compose.yml, with:roif it's read only; to write, the container's user (uid 1000) needs write access to it. - Unraid: in the template, each path (Add another Path…) has its Access Mode: Read Only to show,
Read/Write to upload. The container runs as
99:100(nobody:users), the usual owner of Unraid shares. - TrueNAS SCALE: uid 1000 needs read access to the dataset, and write access to upload; check it in its permissions (ACL).
- Linux, QNAP and Docker Compose: mount the folder with or without
:ro; to write, uid 1000 must be able to.
Step by step in Local folders.
Clouds
KumoYami reads your clouds on the fly, without copying them to the server: OneDrive (personal, business or a shared link), Google Drive, Dropbox, MEGA, Yandex Disk, PikPak, TeraBox, S3-compatible storage, Azure Blob Storage, Bunny Storage, WebDAV, SFTP, FTP/FTPS, Seafile, another Synology's File Station and more. For OneDrive, see Connect OneDrive.
7. Your domain and HTTPS
To get in from outside your home, something in front of KumoYami has to publish it over HTTPS. Pick one:
- On a Synology, DSM's own reverse proxy and certificate, with nothing else to install.
- On Linux or with Docker, a reverse proxy: Caddy or Nginx (the installer sets up Caddy), Nginx Proxy Manager or Traefik.
- Without opening ports: a Cloudflare Tunnel (CGNAT too) or Tailscale, just for your devices, or open to the internet with Funnel.
The Library and Files each go on their own address, and the proxy sends both to port 4890. Then, in Sistema → Módulos (System → Modules), save each module's address: see Save the addresses in Modules and, to choose, Your own domain. To use it only at home, the machine's IP is enough.
8. People: accounts and invitations
In Personas → Ajustes (People → Settings), switch accounts on. From then on, people can get into your site in several ways:
- Local accounts: create or invite them in Personas → Cuentas (People → Accounts). With email set up, they get the invitation and their codes by email; without it, you send them the link yourself.
- Patreon (Pro and Total plans): your campaign's supporters sign in with their Patreon account, and their tier decides which folders and libraries they see.
- Sign in with KumoYami (coming soon): you'll invite people by email from kumoyami.com, and whoever gets the invitation signs in with a free kumoyami.com account, with no new password for your server.
Each library is shared with every account or only with the groups, Patreon tiers or accounts you choose. Profiles and parental controls are in Profiles.
9. The server code, for your visitors
In Sistema → Acceso desde fuera (System → Access from outside), switch on the Código de servidor (server code). Your server gets a short code: whoever types it at kumoyami.com/en/link reaches your site without knowing its address, and KumoYami's apps will find your server with it. Share it, or its link and QR code, with your accounts. See Server code.
/link isn't /activate
kumoyami.com/en/activate is for you: it links your server to your license (step 4), once. kumoyami.com/en/link is for your visitors: it takes them to your server with its code. They're different codes.
10. If you're coming from Plex
You don't start from scratch: Biblioteca → Importar desde Plex (Library → Import from Plex) brings over, for each user of your Plex Home, what they've watched, where they left each video, their watchlist and the artwork you set, without touching Plex or moving a single file. See Import from Plex. For the full move, with what feels the same and what changes, follow the Switch from Plex guide.
11. Backups and updates
- Backups: everything you set up lives in the data folder, next to
docker-compose.ymland.env. Keep those and you have it all: Backups. - Updates: with the installer, Docker Compose, Unraid or Synology's Package Center, in Updating.
- Moving to another machine: in Moving servers.
If something doesn't go as described here, see Troubleshooting.
All trademarks and logos belong to their respective owners. Their use only indicates compatibility, not sponsorship or affiliation. The Synology logo is a trademark of Synology Inc.; Google Drive, Google Cast and Android are trademarks of Google LLC, and the Android robot is reproduced from work created and shared by Google, used under the Creative Commons Attribution 3.0 license. Microsoft, Windows and OneDrive are trademarks of the Microsoft group of companies; Amazon S3 is a trademark of Amazon.com, Inc. or its affiliates; Apple, AirPlay, macOS and iPhone are trademarks of Apple Inc.; Raspberry Pi is a trademark of Raspberry Pi Ltd; Ubuntu is a trademark of Canonical Ltd.; Debian is a trademark of Software in the Public Interest, Inc.; Linux is a trademark of Linus Torvalds. This product uses the TMDB API but is not endorsed or certified by TMDB.