btop, htop or nvtop in a browser tab, served by ttyd, hardened for LAN use. Drop-in replacement for the removed big-bear-btop image.
Why | Built on | Quick start | Switching | Login | Security | Variables | Migration | Image tags | Changelog
docker pull ghcr.io/erreur32/topviewr:latestRenamed: TopviewR was called btop-web up to v1.0.0. The old image
ghcr.io/erreur32/btop-webstill receives the same builds for now, so existing installs keep updating; switch yourimage:line toghcr.io/erreur32/topviewrwhen you can. The old GitHub address redirects here.
Many homelab setups used bigbeartechworld/big-bear-btop to show btop in a browser tab. That image is gone:
- It was removed from Docker Hub. The repository returns 404 and the registry 401, so existing servers can no longer pull or update it, and container managers (Dockhand, Watchtower, Portainer...) report
[Registry] ... 401errors. - It was built on GoTTY, which has been unmaintained since 2024.
- It ran everything as root in a
privilegedcontainer. Anyone who could open the page could presskin btop and kill any process on the host (dockerd, sshd...). - It shipped an old btop that was never updated.
TopviewR is a maintained replacement: same use case and same compose variables, but a current btop, an actively developed web terminal and safer defaults.
- btop 1.4.8 compiled from source (checksum verified, GPU support enabled), on Alpine 3.24, served by ttyd 1.7.7. The image is about 31 MB.
- Rebuilt every week for Alpine security fixes, with a Trivy scan on every build (0 known vulnerabilities on 2026-11-04).
- Automatic btop updates: a weekly job opens a PR when a new btop release is out.
- Multi-arch images:
linux/amd64andlinux/arm64. - NVIDIA GPUs with the
:nvidiavariant (Debian, amd64), see GPU. - Three monitors in one image, picked with
BTOP_TOOL: btop (default), htop 3.5.3 (Alpine package) or nvtop 3.3.2 (GPU monitor, compiled from source). Same login, TLS and non-root protection for all three. - Drop-in compatible: the old
GOTTY_AUTH_*variables still work.
TopviewR only packages and hardens these projects; all the monitoring work is theirs. Thanks to their authors.
| Project | Role in TopviewR | Repository |
|---|---|---|
| default monitor (CPU, memory, disks, network, GPU, processes) | https://github.com/aristocratos/btop | |
alternative process monitor (BTOP_TOOL=htop) |
https://github.com/htop-dev/htop | |
GPU monitor for AMD, Intel and NVIDIA (BTOP_TOOL=nvtop) |
https://github.com/Syllo/nvtop | |
| ttyd by Shuanglei Tao | web terminal: serves the monitor in the browser (auth, TLS, WebSocket) | https://github.com/tsl0922/ttyd |
| Alpine Linux | base image | https://alpinelinux.org |
| tini by Thomas Orozco | init process (signals, zombie reaping) | https://github.com/krallin/tini |
| su-exec by Natanael Copa | runs the monitor as a non-root user | https://github.com/ncopa/su-exec |
| tmux by Nicholas Marriott | switch layer: Esc menu and clickable bar (locked down, no shell) | https://github.com/tmux/tmux |
| Trivy by Aqua Security | vulnerability scan on every build | https://github.com/aquasecurity/trivy |
It replaces bigbeartechworld/big-bear-btop (Docker image and repository now removed), which was built on GoTTY. Licenses: see Credits and license.
| big-bear-btop | TopviewR | |
|---|---|---|
| Image | bigbeartechworld/big-bear-btop (gone) |
ghcr.io/erreur32/topviewr |
| Web terminal | GoTTY (unmaintained) | ttyd 1.7.7 |
| btop version | old, frozen | 1.4.8, updated automatically |
| btop runs as | root | UID 10001 (cannot signal host processes) |
| Password | optional | required, 12 characters minimum with BTOP_PASS |
| HTTPS | no | built in (BTOP_TLS=auto generates a self-signed certificate) |
| WebSocket origin check | no | yes (ttyd -O) |
| Max sessions | unlimited | 3 (BTOP_MAX_CLIENTS) |
| Recommended compose | privileged, /proc, /sys, /dev mounted |
no privileged, cap_drop: ALL + 3 capabilities, read-only root |
What to expect when you switch:
- Legacy compose (step 1 below): nothing changes for you except the image line. A
GOTTY_AUTH_PASSshorter than 12 characters still works but logs a warning. - Hardened compose (step 2 below): the URL becomes
https://, your browser warns once about the self-signed certificate, and you need a new password of at least 12 characters in.env. Network stats become the host's real interfaces instead of the container's172.17.xone. - Starting without any password is refused, unless you explicitly set
BTOP_NO_AUTH=true. - The mounted config folder is chowned to UID 10001 so btop can save its settings.
Pick the compose file for your machine (all three have the same hardened setup, see GPU):
| Machine | Compose file | Image |
|---|---|---|
| no GPU (or not needed) | docker-compose.yaml |
topviewr:latest |
| AMD or Intel GPU | docker-compose.amd-intel.yaml |
topviewr:latest |
| NVIDIA GPU | docker-compose.nvidia.yaml |
topviewr:nvidia |
cp .env.example .env
# edit .env: BTOP_PASS (12 characters min.), BTOP_TLS_SAN (server IP and hostname)
cp docker-compose.amd-intel.yaml docker-compose.yaml # only for a GPU: or docker-compose.nvidia.yaml
docker compose up -dOpen https://<server-ip>:7681. The browser warns once that the certificate is self-signed: accept the exception, then log in.
The page opens on the default tool (BTOP_TOOL, btop unless set) with a one-line bar at the bottom:
TopviewR @ host Alt+1 [ btop ] Alt+2 htop Alt+3 nvtop Esc: menu
- Click
btop,htopornvtopin the bar, or press Alt+1, Alt+2, Alt+3 (with or without Shift, so AZERTY keyboards work too), to switch at once. Plain1,2,3stay with the tools (btop shows or hides its boxes, htop searches a PID). - Esc opens the switch menu on top of any tool:
1btop,2htop,3nvtop (or arrows + Enter, or the mouse), Esc a second time sends a real Esc to the current tool (closes btop's own Options/Help/Quit menus, a search in htop),qcloses this menu and goes back to the tool,xcloses the session. - Quitting a tool (
q,F10) shows a small list to pick another one. - Inside a tool, the mouse keeps working as usual (btop and htop are clickable).
This layer is a locked-down tmux: every default tmux binding is removed (no prefix key, no command prompt, no new window or split), so it cannot open a shell; the only actions are starting one of the three tools and closing the session. tests/test.sh checks the binding list. Each browser tab gets its own tmux instance, destroyed when the tab closes. Set BTOP_MENU=false to start the tool directly, without the bar and the menu (old behavior).
The login lives in a .env file next to the compose file; the compose file only refers to it, so the password is never written in docker-compose.yaml.
# .env (never commit it, chmod 600)
BTOP_USER=admin
BTOP_PASS=change-me-at-least-12-chars # openssl rand -base64 18# docker-compose.yaml
environment:
BTOP_USER: ${BTOP_USER:-admin}
BTOP_PASS: ${BTOP_PASS:?set BTOP_PASS in .env}Docker Compose reads .env from the same folder by itself. Without BTOP_PASS, docker compose up refuses to start; with fewer than 12 characters, the container refuses to start. The browser then shows a standard login prompt (HTTP basic auth).
Legacy compose files that set GOTTY_AUTH_USER / GOTTY_AUTH_PASS directly in environment: keep working (see migration).
What is protected
| Risk | Protection | Checked by |
|---|---|---|
Killing host processes with the k key |
btop runs as UID 10001 (su-exec), never root |
tests/test.sh: kill on host PID 1 is refused |
| Password sniffed on the network | built-in TLS (BTOP_TLS=auto) |
HTTPS test |
| Starting unprotected | refused without a password; 12 characters minimum | test |
| Malicious page opening the WebSocket | ttyd -O (origin checked) |
test |
| Too many btop sessions | 3 clients max (BTOP_MAX_CLIENTS) |
|
| Overpowered container | compose without privileged, cap_drop: ALL + 3 capabilities, read_only, no-new-privileges |
|
| Known vulnerabilities in the image | Trivy scan on every build | make scan |
Password read in ps by another host account |
ttyd gets -c TTYD_CREDENTIAL; a small LD_PRELOAD shim (ttyd-cred.c) swaps in the value from ttyd's environment, readable only by root |
test |
Known limits
- Root on the host can still read the password (
docker inspect, the environment of ttyd), like any container secret, and so can members of thedockergroup. Use a dedicated password, never reused elsewhere. - No brute-force protection. ttyd does not rate-limit attempts. Never expose the port to the Internet. For remote access use a VPN (WireGuard, Tailscale) or a reverse proxy with SSO plus
BTOP_AUTH_HEADER(the port must then only be reachable by the proxy). - ttyd itself runs as root (it reads the certificates and starts btop); only btop, the keyboard-driven part, is non-root. A small root
shstays between ttyd and the tool: withoutCAP_KILL, ttyd may not signal the non-root tool, but it can stop thissh, which ends the whole session when the tab closes.
| View | docker-compose.yaml (hardened) |
docker-compose.legacy.yaml (old compose) |
|---|---|---|
| CPU, memory, uptime | ✅ | ✅ |
| Host processes | ✅ (pid: host) |
✅ (/proc mounted) |
| Real host network | ✅ (network_mode: host) |
❌ only the container interface (172.17.x) |
| Host disks | ✅ via /:/host:ro,rslave |
not checked |
| GPU | ✅ AMD and NVIDIA (see GPU) | not tested |
Two images, same tools, scripts and hardening. Both start fine without a GPU: nvtop then says what to mount instead of crashing, and the startup header lists what it found.
| Image | Base | GPU | Size |
|---|---|---|---|
ghcr.io/erreur32/topviewr:latest |
Alpine (musl), amd64 + arm64 | AMD, Intel | ~31 MB |
ghcr.io/erreur32/topviewr:nvidia |
Debian 13 (glibc), amd64 | NVIDIA, AMD, Intel | ~155 MB |
NVIDIA needs its own image: btop and nvtop read NVIDIA GPUs through libnvidia-ml, which the NVIDIA container runtime mounts from the host driver. That library is built for glibc and crashes the tools on Alpine (musl).
Both GPU files are the default docker-compose.yaml plus a few lines. Check with docker logs <container>: the GPU line of the startup header must list your GPU, not none.
docker-compose.yaml, as is. btop and htop work fully; nvtop says it found no GPU and what to mount.
docker-compose.amd-intel.yaml adds the GPU render nodes:
devices:
- /dev/dri:/dev/driOn most hosts /dev/dri/renderD* belongs to the render group (mode 0660); the entrypoint runs the monitor with that group, so it can open the GPU while staying non-root. Startup header: GPU 1 render node(s) in /dev/dri.
- Install the NVIDIA Container Toolkit on the host:
docker info | grep -i runtimesmust listnvidia. - Use
docker-compose.nvidia.yaml, which changes two lines:
image: ghcr.io/erreur32/topviewr:nvidia # fixed: BTOP_IMAGE in .env does not apply here
runtime: nvidiaThe image already sets NVIDIA_VISIBLE_DEVICES=all and NVIDIA_DRIVER_CAPABILITIES=utility (usage, VRAM, temperatures, processes: all the tools need), so no devices: or environment: lines are needed. Same read-only, non-root, no-new-privileges setup. Startup header: GPU 1 render node(s) in /dev/dri, 1 NVIDIA GPU(s) and Image Debian 13.x, NVIDIA ready.
The image is fixed in that file on purpose: with the default .env (BTOP_IMAGE=...:latest), a ${BTOP_IMAGE} line would silently run the Alpine image, where NVIDIA cannot work.
Tested on 2026-11-10 with the hardened compose (non-root, read-only):
| GPU | btop | nvtop |
|---|---|---|
| AMD (amdgpu), Radeon 8060S | ✅ via /sys (integrated GPUs too, new in btop 1.4.8) |
✅ via libdrm: usage, clocks, VRAM, temperature, power, processes |
NVIDIA (:nvidia image), RTX 3060 Ti, driver 550 |
✅ GPU meter | ✅ via NVML: usage, clocks, VRAM, temperature, fan, power, processes (other users' too) |
| Intel (i915 / xe) | partial: usage needs perf access, blocked for non-root when kernel.perf_event_paranoid > 2 (Debian default: 3) |
✅ via libdrm (not tested on hardware) |
- Per-process GPU usage on AMD and Intel is read from
/proc/<pid>/fdinfo. As a non-root user, nvtop only sees it for processes it is allowed to inspect: global usage, VRAM and temperatures are shown, but GPU processes owned by root or by other users may be missing from the process list. That is the price of running non-root. NVIDIA reports processes through the driver, so they all show. - The
:nvidiaimage ships Debian's htop 3.4.1 (Alpine: 3.5.3); btop, nvtop and ttyd are the same versions, built from source.
| Variable | Default | Purpose |
|---|---|---|
BTOP_TOOL |
btop |
monitor to run: btop, htop or nvtop |
BTOP_MENU |
true |
bottom bar and Esc menu to switch tools; false starts BTOP_TOOL directly |
BTOP_USER / GOTTY_AUTH_USER |
admin |
username |
BTOP_PASS / GOTTY_AUTH_PASS |
required | password (BTOP_* wins) |
BTOP_NO_AUTH=true or GOTTY_AUTH_ENABLED=false |
disables auth (not recommended) | |
BTOP_ALLOW_WEAK_PASS |
false |
accepts fewer than 12 characters (tolerated with a warning for GOTTY_AUTH_PASS) |
BTOP_TLS |
off in the image, auto in the compose |
off, auto (self-signed, generated in /certs), on (provide /certs/cert.pem and key.pem) |
BTOP_TLS_SAN |
IPs and names added to the certificate, comma-separated | |
BTOP_PORT |
7681 |
port |
BTOP_BIND |
all | listen IP or interface |
BTOP_UID / BTOP_GID |
10001 / group of /dev/dri/renderD* if mounted, else 10001 |
monitor user (chosen to match no host account) and group (the render group gives GPU access) |
BTOP_MAX_CLIENTS |
3 |
concurrent sessions |
BTOP_TITLE |
TopviewR @ <hostname> |
browser tab title |
BTOP_FONT_SIZE |
16 |
font size |
BTOP_THEME |
dark |
light for a light background |
BTOP_AUTH_HEADER |
auth done by a reverse proxy (ttyd -H) |
|
BTOP_DEBUG |
false |
true adds ttyd's notices to the logs (each connection, startup config); by default only errors and warnings |
BTOP_ARGS, TTYD_EXTRA_ARGS |
extra btop and ttyd options |
btop config: ./config/btop.conf, created on first start if missing (never overwritten). By default use_fstab = false and Docker's fake disks are filtered out, so the real host disks are shown.
First keep a copy of the old image if it is still cached:
docker image ls | grep big-bear && docker save bigbeartechworld/big-bear-btop -o big-bear-btop.tarStep 1: drop-in replacement (nothing else changes). In your current compose file, only replace:
image: ghcr.io/erreur32/topviewr:latestthen docker compose up -d. GOTTY_* variables keep working. See docker-compose.legacy.yaml.
Step 2: switch to the hardened compose. Copy docker-compose.yaml and .env.example next to the old one, fill in .env (BTOP_CONTAINER_NAME with your old container name, a new password, BTOP_TLS_SAN), move the old .config/ folder to config/, then docker compose up -d. The URL becomes https://.
Step 3: re-enable automatic updates in your container manager.
Rollback: pin a previous dated tag (image: ghcr.io/erreur32/topviewr:1.4.8-20261104), or load the old image from the copy: docker load -i big-bear-btop.tar.
| Tag | What it is | When to use it |
|---|---|---|
latest |
last build of main |
automatic updates (Watchtower, Dockhand...) |
v1.0.0 |
a TopviewR release (see CHANGELOG) | pin a known version |
1.4.8 |
last build shipping btop 1.4.8 | follow one btop version, still get Alpine fixes |
1.4.8-YYYYMMDD |
a dated weekly build | rollback |
nvidia, v1.4.0-nvidia, 1.4.8-nvidia, 1.4.8-YYYYMMDD-nvidia |
the same, Debian variant for NVIDIA GPUs (amd64) | NVIDIA hosts, see GPU |
TopviewR has its own version (v1.0.0, v1.1.0...); the btop version it ships is in the io.btop.version image label and in the changelog.
make build # local image topviewr:dev
make test # build + end-to-end tests (needs Docker and python3)
make test-nvidia # same for the Debian (NVIDIA) variant, topviewr:dev-nvidia
make scan # Trivy
make buildx # amd64 + arm64 without push (needs QEMU/binfmt for arm64)
scripts/dev.sh # local test server from this tree (hardened compose, port 7682, logs in the foreground)
REGISTRY=ghcr.io/erreur32 make pushBumping btop by hand: change BTOP_VERSION and BTOP_SHA256 in Dockerfile and Dockerfile.nvidia (curl -fsSL https://github.com/aristocratos/btop/archive/refs/tags/vX.Y.Z.tar.gz | sha256sum).
build.yml: on every push, every PR and every Monday. Build, tests, Trivy, then multi-arch push toghcr.io/erreur32/topviewr(and to the old nameghcr.io/erreur32/btop-webduring the transition) with tagslatest,1.4.8and1.4.8-YYYYMMDD.btop-release.yml: every Monday, opens a PR when a new btop release is out. PRs created withGITHUB_TOKENdo not trigger CI: close and reopen it, or runbuildby hand.release.yml: on eachvX.Y.Ztag, creates the GitHub release with the matching CHANGELOG section;build.ymlpushes thevX.Y.Zimage tag at the same time.codeql.yml: CodeQL analysis of the workflows and the Python test client, on every push, every PR and every Monday.- Dependabot: GitHub Actions and Alpine base image versions, plus security alerts and fixes.
TopviewR's own files (scripts, compose files, Dockerfile, docs) are released under the Apache License 2.0. The image bundles these unmodified third-party programs, each under its own license; their license texts are in the image under /usr/local/share/licenses/ and in licenses/:
| Program | Version | License | Source code |
|---|---|---|---|
| btop by aristocratos | 1.4.8 | Apache-2.0 | v1.4.8 tarball, built by the Dockerfile |
| htop by the htop authors | 3.5.3 | GPL-2.0-or-later | Alpine package, source in Alpine aports and upstream 3.5.3 |
| nvtop by Maxime Schmitt | 3.3.2 | GPL-3.0-or-later | 3.3.2 tarball (sha256 in the Dockerfile), built unmodified by the Dockerfile |
| ttyd by Shuanglei Tao | 1.7.7 | MIT | Alpine package, upstream 1.7.7 |
| tmux by Nicholas Marriott and contributors | 3.7c | ISC | Alpine package, upstream |
The other packages come from Alpine Linux 3.24 unchanged, under their own licenses. The TopviewR logo in assets/ is original; btop, htop, nvtop and ttyd are the names of their own projects. The btop, htop and nvtop logos in assets/apps/ are copied unmodified from their repositories (btop Img/icon.svg, htop htop.svg, nvtop desktop/nvtop.svg) and stay under their projects' licenses.