Documentation

Privacy and security

Home Stream runs in your house, on your machine, for your household. It is designed so that your library, your history and the rest of your home network stay that way.

What leaves your house

The server only reaches out to the internet to fill in details and pictures, and to check a sign-in with Apple. Here is everything it contacts:

• The Movie Database (TMDb) provides film and television details, posters, cast and certifications, and the films showing in cinemas near you. To look something up, the server sends the title and year it read from the file name, along with your own TMDb key.
• MusicBrainz provides album and artist details. Cover Art Archive, whose covers are stored at the Internet Archive, provides album covers.
• Wikipedia, Wikidata and Wikimedia Commons provide artist biographies and photographs. TheAudioDB is used as well if you add a key for it.
• Apple is contacted when someone signs in with their Apple account. The server downloads Apple's public keys to check the sign-in is genuine. It holds no Apple account and no Apple credentials.
• YouTube is contacted only when somebody plays a trailer that isn't in your library. Their browser plays it from YouTube's privacy-enhanced address, and the Apple TV hands it to the YouTube app. Trailers can be turned off for the household or per person. Child accounts are never offered them.

The machine itself also checks the image registry once a day, at the hour you chose, for a newer version of Home Stream.

Made for your home network

Home Stream is meant to be reached only from inside your home. It uses plain http rather than https, because the certificates that make https work can't normally be issued for a private address on a home network.

That has one real consequence. Without https, a browser's sign-in can't be marked as secure-only, so someone already on your network could capture it. The page's own scripts still can't read it. Treat your Wi-Fi password as the front door. If you give visitors Wi-Fi, a separate guest network is a good idea.

Watching away from home isn't supported yet. Don't open a port on your router to reach Home Stream from outside. The design notes recommend a VPN into your home network instead. Proper remote access is planned as a switch the administrator controls, off by default.

It answers only to names it knows

A web page on the internet can try to reach devices on your home network through your own browser, by pointing a name of its own at them. To stop this, Home Stream only answers when it is addressed by a name a household would use:

• a numeric address,
• a single-word name, like homeserver,
• a name ending in .local, .lan, .home, .internal or .home.arpa,
• or localhost.

Anything else gets "This server does not answer to that name." If you really do use a full domain name for it at home, add that name to HOMESTREAM_HOSTNAMES. Several names can be separated with commas. Put it in the environment section of compose.yaml, because the server doesn't read it from .env on its own:

    environment:
      TZ: ${TZ:-UTC}
      PUBLISHED_PORT: ${PORT:-8080}
      HOMESTREAM_HOSTNAMES: media.example.com

Then run docker compose up -d from the folder that holds compose.yaml and .env (~/homestream if you used the installer).

Setting up and getting back in, from home only

A brand-new server answers nothing but its setup screen. It can't show your library, your settings or your folders to anyone until it has an administrator. The only exception is a version check, because a version number isn't a secret.

To set it up, you need the setup code. The server prints it to its log and keeps it in a file only the server's user can read. Having the code proves you have access to the machine itself, which is the right test for the person who owns it. Setup is also refused from anywhere except your home network. That way, a server accidentally reachable from the internet can't be taken over by whoever finds it first.

The recovery code that resets a lost password follows the same rules. It is kept in a file beside the database, never written to the log, and replaced as soon as it is used. Recovery only works from your home network. A request that arrives through another server, such as a proxy, is refused for both setup and recovery.

Accounts and signing in

• Passwords are stored only as hashes. They are scrambled one way, so nobody can read a password back out of the database. A password needs at least ten characters.
• Sign-ins are stored as digests. A copy of the database, from a backup or a drive taken out of the machine, can't be used to sign in as anyone.
• Two-factor sign-in adds a six-digit code from an authenticator app. It works without an internet connection and sends nothing anywhere. You get backup codes for a lost phone. Changing your password, turning two-factor off or making new backup codes all ask for a code as well as your password. Set it up under Settings → Security.
• You can see every device you are signed in on under Settings → Users & Devices. Ending one signs that device out straight away. Sign Out Everywhere Else ends all but the one you are using. Changing your password does the same.
• Guessing is slowed down. Repeated wrong passwords, setup codes, recovery codes, invitations and pairing codes are held back, one address at a time.
• Approving a new device is two steps. Before you let a television or browser in, you see the name it gave, when it asked, and whether it asked from your home network.
• Roles are enforced by the server, not just the screen. Only the administrator manages accounts and library folders. Child accounts see only what their age allows, and nothing unrated.

What the server itself is allowed to do

• It runs with as few rights as possible. The container runs as an ordinary user rather than as the machine's administrator, gives up every special privilege, and can't gain new ones. Its own files can't be changed. The only places it can write are its data folder and your library folders.
• It can't update itself. There is nothing in it that fetches and runs new code. Updates come from the machine replacing the whole image.
• Pictures come only from a short list of sources, always over https, with a size limit. A picture address that points anywhere else is refused.
• It plays files only from inside your library. A shortcut in a library folder that points somewhere else on the machine won't be followed.
• Every picture goes through the same rules as the title it belongs to, so a child account can't fetch the poster of a film it isn't allowed to see.
• Other websites can't put Home Stream inside their own pages, and they can't submit forms to it on your behalf.

Choosing library folders

Give Home Stream the folders your media is in, and nothing more.

• It refuses the whole disk, system folders, and its own data folder as library folders.
• Only the administrator can add, change or remove a library folder.
• The container can only see folders listed under volumes in compose.yaml. List your media folders there, not their parent or the whole drive.
• Uploads, deleting, Move files… and renaming a file to match its title all write to the library. If you don't want Home Stream to do those things in a folder, you can mount it read-only by adding :ro to its line under volumes.