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. |
||
|---|---|---|
| .gitignore | ||
| docker-compose.yml | ||
| Dockerfile | ||
| entrypoint.sh | ||
| LICENSE | ||
| README.md | ||
| truenas-app.yaml | ||
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.
-
Bind one address, never
0.0.0.0. The default is127.0.0.1; reach it over an SSH tunnel:ssh -L 6080:127.0.0.1:6080 user@your-serverPut 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.
-
Set
VNC_PASSif 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. -
PROFILE_DIRis a credential, not a cache. Anyone who copies it is logged in as whatever accounts you signed into. Keep it600, out of shares, out of git, and out of any backup that is not encrypted. -
restart: "no"is deliberate. It should not silently come back after a reboot holding live sessions. -
Keep the container off the public internet. It runs Chromium as root with
--no-sandboxand 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:
- 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. - Apps → Discover → Custom App → Install via YAML, using
truenas-app.yaml. - 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.