Minimal noVNC + Chromium container: a remote browser for a headless, always-on server.
Find a file
justin 4f563aea61 make entrypoint.sh executable in the repo
The Dockerfile chmods it inside the image, so the container worked, but the
stored mode was 100644 - a clone or bind-mount would have hit a permission
error. git had no exec bit to record.
2026-10-30 01:24:08 +08:00
.gitignore novnc-chromium: minimal remote browser for a headless server 2026-10-30 01:23:56 +08:00
docker-compose.yml novnc-chromium: minimal remote browser for a headless server 2026-10-30 01:23:56 +08:00
Dockerfile novnc-chromium: minimal remote browser for a headless server 2026-10-30 01:23:56 +08:00
entrypoint.sh make entrypoint.sh executable in the repo 2026-10-30 01:24:08 +08:00
LICENSE novnc-chromium: minimal remote browser for a headless server 2026-10-30 01:23:56 +08:00
README.md novnc-chromium: minimal remote browser for a headless server 2026-10-30 01:23:56 +08:00
truenas-app.yaml novnc-chromium: minimal remote browser for a headless server 2026-10-30 01:23:56 +08:00

novnc-chromium

A minimal, always-available remote browser for a machine that has no monitor.

No desktop environment, no window manager, no audio, no GPU. Xvfb draws one screen, Chromium fills it, x11vnc serves that screen on loopback, and websockify publishes it as an ordinary web page. Roughly 400 MB.

Why you'd want this

Lots of services still only offer a web UI and nothing else — no usable API, no command-line client. Downloading a large archive, exporting an account, or reaching a router that insists on a browser all assume you have a screen in front of you.

A home server or NAS is already on, already cheap to run, and already has the disk. The one thing it lacks is a display. This gives it one you can reach from your laptop or phone, and it can keep the signed-in session indefinitely — so a slow download does not mean keeping a desktop awake for hours.

What it is, and what it is not

It gives you It does not give you
A reachable browser on a headless box Any automated downloading
A persistent login in /profile that survives restarts Bulk export from services that don't offer one
Re-login when a session expires, from any device A substitute for a service's own export tool
A browser profile a headless tool can reuse later Workarounds for per-service rate or batch limits

Read that right-hand column. This container is the browser, not the downloader. Where a service caps bulk downloads in its UI, or needs dozens of manual cycles, that is a problem above this layer — the right answer is usually that service's official export (an archive, a takeout, an API), not a browser automation hack.

Run it

docker compose up -d --build

Open http://127.0.0.1:6080/vnc.html. Sign in to whatever you need, then leave it — closing the tab does not end the session; the profile directory keeps it.

docker compose down

Configuration

Everything is an environment variable with a safe default:

Variable Default Notes
BIND_ADDR 127.0.0.1 Never 0.0.0.0. Use a tunnel, or a VPN/LAN address you control
PORT 6080 Published host port
TZ UTC Container timezone
SCREEN 1440x900x24 Virtual display geometry
START_URL about:blank Page opened on start
VNC_PASS (empty) Set it, or rely on the bind address
PROFILE_DIR ./data/profile Credential. The signed-in session
DOWNLOADS_DIR ./data/downloads Where browser downloads land
MEM_LIMIT / CPUS / SHM_SIZE 1536m / 1.0 / 512mb Sized for a small box

Security — read before you publish the port

This container is a browser with your logins in it, served over plain HTTP.

  1. Bind one address, never 0.0.0.0. The default is 127.0.0.1; reach it over an SSH tunnel:

    ssh -L 6080:127.0.0.1:6080 user@your-server
    

    Put it on a VPN or a LAN address only if you accept that everyone on that network can use the browser and every session inside it.

  2. Set VNC_PASS if it listens on anything but loopback. A password over plain HTTP is weak, but far better than nothing — and put TLS in front of it if it leaves your LAN.

  3. PROFILE_DIR is a credential, not a cache. Anyone who copies it is logged in as whatever accounts you signed into. Keep it 600, out of shares, out of git, and out of any backup that is not encrypted.

  4. restart: "no" is deliberate. It should not silently come back after a reboot holding live sessions.

  5. Keep the container off the public internet. It runs Chromium as root with --no-sandbox and a relaxed seccomp profile to work inside a container; that trade is acceptable on a machine you control and not otherwise.

Deploying on TrueNAS

TrueNAS manages apps itself, so docker compose up --build from a shell is the wrong path: it bypasses app management, lands outside the app dataset, and is invisible to the Apps UI. But TrueNAS Custom Apps run a published image and have no build step, so:

  1. Build and publish the image to a registry your NAS can reach, or skip the build and use a maintained equivalent such as lscr.io/linuxserver/chromium.
  2. Apps → Discover → Custom App → Install via YAML, using truenas-app.yaml.
  3. Edit that file first: set the image reference, the host paths, and the bind address.

Host paths must exist and be writable by the app's user before first start.

Alternatives

Size Notes
This image ~400 MB No desktop layer; ~40 lines of Dockerfile you can read
lscr.io/linuxserver/chromium ~1 GB Actively maintained, KasmVNC, more features
lscr.io/linuxserver/firefox ~1 GB Same, Firefox

Licence

MIT — see LICENSE.