← All docs

Before you start

• A machine that runs Docker on 64-bit x86 or 64-bit ARM: a Linux server or a NAS that supports Docker. We do not publish a list of tested NAS models.
• The Beebo server Docker image — not offered for download right now (see the status note above).
• Your movies, TV, music and photos in folders the container can read.
• A safe place to keep one secret key (step 2).

Step by step

1. Make folders for settings and media

   Create a folder for Beebo’s own data, for example /srv/beebo/config. Beebo keeps its settings, accounts, watch history, saved artwork and certificates there. Also note where your media folders are.

   Beebo only needs to read your media folders to play them. Uploads from the phone app, the Inbox and file clean-up do write to the media folders, so give Beebo write access too if you want those.

2. Make a secret key and keep it

   Beebo encrypts the secrets it saves in its settings file, such as sign-in signing keys, your TMDB key, webhook secrets, two-factor secrets and away-from-home passes. It needs one secret key to do that. You give Beebo the key through an environment variable (a named setting you pass to the container when you start it).

   Make a key, for example with openssl rand -hex 32, and save it somewhere safe. If you change or lose it, the saved secrets become unreadable. Beebo then stops at start-up with a message, instead of quietly signing everyone out.

   What you’ll see: A 64-character string. Keep it outside the config folder if you want real separation: anyone who has the whole config folder and the key file has both.

3. Start the container

   Once the image is offered for download again, start it like this. The last built tag is 0.1.58, older than the current Windows app (0.1.113); a newer image will be posted when it is ready. Pin a version number rather than latest if you want to control exactly when you upgrade:

   docker run -d --name beebo --restart unless-stopped \
     -p 47811:47811 \
     -e BEEBO_UPNP=0 \
     -e BEEBO_SECRET_KEY="<your key>" \
     -v /srv/beebo/config:/config \
     -v /srv/media/movies:/media/movies:ro \
     -v /srv/media/tv:/media/tv:ro \
     -v /srv/media/music:/media/music:ro \
     -v /srv/media/photos:/media/photos:ro \
     ghcr.io/swgfan/beebo-server:0.1.58

   The :ro at the end of each media folder line means “read-only”: Beebo can play the files but not change them. That is fine for watching. Leave it off if you want uploads from the phone app, the Inbox and file clean-up to write to those folders. Add /media/audiobooks the same way for audiobooks.

   If your files belong to another user, see Folders and users below (--user, or PUID and PGID). A wrong setting stops the container with a message listing every problem (exit code 78), so a typo does not start an empty server.

   Screenshot coming. A NAS container manager with the Beebo container running.

4. Read the first-run message

   A new server has no accounts. It prints a one-time message to its log (the text the container writes as it runs). To read it, run docker logs beebo.

   What you’ll see: Lines like “First-run setup: this server has no owner account yet.”, an address such as https://192.168.1.20:47811/setup and a setup code shaped like 7KQ2-M9XD-4TNB.

5. Create the owner account

   1. In a web browser, open the address from the log (it starts with https and ends in :47811/setup).
   2. Your browser will warn about the certificate (the server’s security ID card). That is because Beebo made the certificate itself (it is “self-signed”). Accept the warning to continue.
   3. Type the code from the log into Setup code.
   4. Choose an Owner username and a password of 8 or more characters, and type the password again in Repeat password.
   5. Click Create owner account.

   Setup closes for good once the account exists. If you miss the message, restart the container for a new code. The code lives only in the log and in memory.

   What you’ll see: A sign-in page. Sign in at https://<server-ip>:47811/. The admin pages only open over HTTPS. Phones and TVs on your network can keep using http://<server-ip>:47811.

6. Add posters and connect your devices

   Posters and movie information come from TMDB, a free movie database. Give Beebo a TMDB key with the BEEBO_TMDB_API_KEY environment variable (see the free key steps in Get started on Windows). Then connect phones and TVs to http://<server-ip>:47811 as in Connect your phone. Replace <server-ip> with your server’s address on your home network.

Folders and users

The server never runs as root (the all-powerful administrator account on Linux). The user it runs as must be able to read your media and /config, and to write to /config. Either run the container as the owner of your files (user: in compose, or --user with docker run), or start as root and set PUID and PGID so Beebo takes ownership of /config and then drops to that user. Typical values: Synology 1026:100, Unraid 99:100, TrueNAS SCALE 568:568. On QNAP use your user’s id (id <user> over SSH). Beebo’s port can be changed with BEEBO_PORT, but that changes the address phones use.

Networking and video conversion

• Bridge (default): publish port 47811 (TCP). Phones on your network use http://<nas-ip>:47811. The router cannot be reached from a bridged container, so automatic port mapping (UPnP) does not work: keep BEEBO_UPNP=0.
• Host network (Linux): the container uses the machine’s network, so router port mapping works as on the desktop. TCP 47811 and UDP 47820–47829 then belong to this container.
• Reverse proxy: Beebo’s admin pages need HTTPS to Beebo itself, so proxy to https://<nas>:47811 and accept its certificate, or place your own cert.pem and key.pem in /config/certs.
• Hardware conversion: video that a device cannot play as it is gets converted while it plays. It works on the processor by default. For an Intel or AMD graphics chip, pass in the device with --device /dev/dri and the group that owns it (--group-add $(stat -c %g /dev/dri/renderD128)). For NVIDIA, install the NVIDIA Container Toolkit on the host and add --gpus all. On Unraid an Intel graphics chip is added as the device /dev/dri. Raspberry Pi uses the processor only. We have not tested any of this on real graphics hardware, and whether a given encoder is available depends on the video tool bundled in the image; tell us what works for you.

What is in v1, and what is not

Beebo itself is proprietary software. The image includes FFmpeg under the LGPL; you may swap in your own build with BEEBO_FFMPEG. You can also run the same server directly with Node 22 or newer, without Docker.

If something goes wrong

Related pages

Checked against Beebo for Windows 0.1.79 and the Android test build 1.51-tester12 (build 62) on October 5, 2026. Found something that doesn’t match what you see? Tell us at testers@beeboentertainment.com. It is a plain email, with no form and no sign-up.