docker-handbrake: HandBrake in a browser, with nothing to install

The desktop application, delivered over HTTP

The project provides a lightweight and secure Docker container for HandBrake, and the way it delivers the application is the interesting part. You access the application's full graphical interface directly from any modern web browser, with no downloads, installs or setup required on the client side, or you connect with any VNC client.

That is a different proposition from a command line encoder. HandBrake is a rich graphical tool with a preset system, a preview and a queue, and that interface is the reason people use it. Putting a browser in front of it means the tool can live on a server, a NAS or a homelab box, and be used from a laptop, a tablet or a phone, with the client side reduced to a browser.

The README is careful about the limits of the arrangement, and lists what the web interface adds on top of the application: audio playback, seamless clipboard sharing, an integrated file manager and terminal for accessing the container's files and shell, desktop notifications, and more.

Two details are worth noting early. The container is described as entirely unofficial and not made by the creators of HandBrake, so it is a third-party packaging of upstream HandBrake, and it is a container of a graphical application, which brings with it the usual questions about who can reach the port and what happens when the browser session expires.

The watch folder is the part that changes how you work

A fully automated mode is also available: you drop files into a watch folder and HandBrake processes them without any user interaction.

For a server, that is the feature that turns this from a remote desktop into a service. A NAS that watches an incoming folder for a downloaded file and encodes it overnight, with a preset applied automatically, is a small pipeline, and the fact that it reuses the same HandBrake presets means the output matches what the application would produce.

The table of contents shows that the watch folder is a first-class concept rather than a script bolted on. There is a section on multiple watch folders, a section on running multiple containers for the same purpose, a section on video discs, a section on hooks, and a section on a staging conversion directory. That last one is a design decision with real consequences: a staging directory lets the system collect an input and its output together before moving them, which is what you need if the conversion has to be atomic from the point of view of whatever is watching the output folder.

Hooks are the other structural piece, since a hook lets the container run something when an event happens, and that is what turns a queue into a pipeline with steps.

Four directories, one of them read only

The quick start command is a good summary of the design, since each mount has a clear job:

docker run -d \
    --name=handbrake \
    -p 5800:5800 \
    -v /docker/appdata/handbrake:/config:rw \
    -v /home/user:/storage:ro \
    -v /home/user/HandBrake/watch:/watch:rw \
    -v /home/user/HandBrake/output:/output:rw \
    jlesage/handbrake

The /config directory stores the application's configuration, state, logs and any files that need to persist, and the README points at a path under /docker/appdata for it, which is the conventional layout for this author's images. The /storage directory holds files from the host that need to be accessible to the application, and it is mounted read only, which is a good default: the container can read your media but cannot modify it.

The /watch directory is where videos are placed to be converted automatically, and /output is where the converted files land. Both are read write, of course, since that is the point of them.

Files from the host appear under the /storage folder inside the container, and the graphical interface is reached by browsing to http://your-host-ip:5800.

The README is explicit that the command in the quick start is an example and that the parameters should be adjusted to suit your needs, which is worth remembering since the paths are obviously specific to one machine.

The web layer, and the parts that are not HandBrake

Separating HandBrake from the container's own features helps to understand what you are actually deploying. The container adds a web control panel, host clipboard sync, web audio, a web file manager, web notifications, a web terminal and a web app that can be installed as a PWA.

The PWA point is the interesting one for a media server, since it means the interface can be added to a phone's home screen and behave like an app, which is what makes a browser-based tool viable on a phone at all.

The clipboard sync and the web file manager exist because a browser is otherwise awkward with a server-side desktop application. HandBrake's own file dialogs and copy and paste do not map cleanly onto a web session, so the container bridges them.

The rest of the table of contents covers the operational surface: a reverse proxy section with routing based on hostname and routing based on URL path, a shell access section, a section on user and group IDs, and separate sections for Synology and unRAID, which are the two platforms where this kind of container is most often wanted and where the storage paths and permissions are awkward enough to need their own instructions.

There is also a section on access to optical drives, which matters for anyone who still rips discs, and a section on changing parameters of a running container.

Security is a section of its own

The container has a substantial security section, which is the right signal to look at before exposing a desktop application to a network. It covers SSVNC, the certificates used, the VNC password, and web authentication with a subsection on configuring user credentials.

The four items cover the four ways in. The SSVNC subsection comes first, so its configuration is the first question. The certificates determine whether the browser connection is encrypted and whether the certificate warning appears. The VNC password protects the VNC path separately from the web path. And web authentication is the layer in front of the browser interface, which by default is not protected at all.

The reverse proxy section follows naturally, and it is the way most people will expose this: the container's own port sits behind a proxy that terminates TLS, and the routing options, by hostname or by URL path, exist so that several containers can share one proxy.

The environment variable table gives the identity settings the container uses, with USER_ID and GROUP_ID defaulting to 1000, a SUP_GROUP_IDS variable for supplementary groups, and a UMASK that defaults to 0022 so that files and folders are readable by others. Those defaults matter for a NAS, where the files end up on a share that other users and services read.

Hardware acceleration, and the Intel stack in the Dockerfile

Encoding video is the one workload where hardware acceleration genuinely changes the economics, and the Dockerfile shows how seriously this project takes it. The build arguments pin the whole Intel media stack: HANDBRAKE_VERSION at 1.11.2, LIBVA_VERSION at 2.23.0, INTEL_VAAPI_DRIVER_VERSION at 2.4.1, GMMLIB_VERSION at 22.9.0, INTEL_MEDIA_DRIVER_VERSION at 25.4.6, INTEL_MEDIA_SDK_VERSION at 23.2.2, INTEL_ONEVPL_GPU_RUNTIME_VERSION at 25.4.6 and CPU_FEATURES_VERSION at 0.11.0.

That is libva, the Intel VAAPI driver, gmmlib, the Intel media driver, the Intel Media SDK, the oneVPL GPU runtime and Google's cpu_features, each fetched from its own release archive.

The README has a dedicated section on Intel Quick Sync Video, with a further unRAID subsection, and a section on GPU acceleration support more generally. The practical effect for a user is that on a machine with an Intel iGPU, the container can encode with the hardware encoder, which is several times faster and considerably less power hungry than software encoding.

There is also a HANDBRAKE_DEBUG_MODE build argument, set to none by default, which can be set to max to keep debug symbols, and the build uses the tonistiigi/xx cross-compilation helper on the build platform, with the HandBrake stage built on alpine:3.20. Cross-compilation is what allows one build to produce images for several architectures, and the README's mention of nightly and debug builds is a consequence of the same setup.

Where a containerised HandBrake is the wrong choice

The first wrong-tool case is a single desktop conversion. If you are at a desk with one machine and one file, the native HandBrake application starts in seconds, uses the local GPU without a container boundary, and has no port to secure. The container exists to solve distribution, and a distribution problem you do not have is not worth a container.

The second is an environment where you cannot run containers with a browser-facing port. A browser interface means an HTTP server, which means a listening port, which means an exposure decision. If your policy is that no service runs on that host, the answer is no.

The third is a workflow that needs the optical drive or a specific hardware path, and where the container's device passthrough and permissions are more trouble than the native application. The README covers access to optical drives, but the general point stands: a container that has to reach a disc drive or a GPU device needs those devices passed in, and that is where the setup stops being simple.

There is one more consideration specific to this project. Since the container is unofficial, it tracks HandBrake versions on its own schedule, and the versioning scheme in the README, with tags such as v26.09.1 following a year and month pattern rather than HandBrake's own numbering, means the relationship between the container tag and the HandBrake version inside it is something you have to look up rather than infer.

MIT, version 26.09.1, and a monthly release rhythm

The project is MIT licensed, with the LICENSE file at the repository root, and the primary language is Shell, which is a fair description of a project that is mostly a Dockerfile, a rootfs/ tree and a set of scripts in src/.

The release list shows v26.09.1 on 2026-09-22, v26.08.2 on 2026-08-17 and v26.08.1 on 2026-08-11, and the last push was on 2026-09-22, the same day as the newest release. So the project ships roughly monthly, with patch releases inside a month, and it is current.

That cadence is the practical strength of the project. A container that pins HandBrake, libva and four Intel driver versions has many moving parts upstream, and a maintainer who rebuilds when those change is providing a service that nobody wants to do themselves. The repository also carries a Dockerfile for the image build, an appdefs.yml, a rootfs/ directory for the filesystem the image layers add, a src/ directory for the scripts, and DOCKERHUB.md for the Hub description, plus a .github/ directory for the build workflow visible in the badge.

The image is published on Docker Hub as jlesage/handbrake, and the README documents the update path for Synology and unRAID, which are the two platforms where a monthly image pull is something you schedule rather than something that happens.

Editorial conclusion

Adopt docker-handbrake if you want HandBrake available to several people or several machines without installing a desktop application on each, or if you want a NAS or homelab box to convert files unattended from a watch folder. Do not adopt it for a single desktop conversion session, where the native application is simpler, and do not assume the container's browser interface is a client for an existing HandBrake installation, because the whole application runs inside the container. Before you deploy, read the security section on SSVNC, certificates, the VNC password and web authentication, and note that the container is entirely unofficial, so you should track the upstream HandBrake releases yourself.

Frequently asked questions

Official sources

1. Issues
2. jlesage/docker-handbrake on GitHub
3. License: MIT
4. README
5. Releases