web-terminal-server

command module
v1.15.14 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 20, 2026 License: MPL-2.0 Imports: 19 Imported by: 0

README

web-terminal-server

Image Size Platforms Test coverage OpenSSF Best Practices OpenSSF Scorecard SBOM

A small, generic web terminal: it runs a configured command in a PTY and serves the @cplieger/web-terminal-ui front end over HTTP + WebSocket, built on the github.com/cplieger/web-terminal-engine engine. A native-touch terminal in the browser for any command, on phone and desktop alike.

Published as a multi-arch (amd64 + arm64) container image on GHCR (ghcr.io/cplieger/web-terminal-server) and Docker Hub (cplieger/web-terminal-server).

⚠️ Security: this is a remote shell

Anyone who can reach the server and pass auth (if configured) gets an interactive process running WT_CMD with this server's privileges. Treat it like exposing SSH.

  • The binary binds 127.0.0.1 by default. Reachable only from the same host until you change WT_ADDR.
  • The container image binds :7681 (it has to, to be reachable via a published port) and so is unauthenticated and network-exposed by default. Before exposing it beyond a trusted host, do one of:
    • set WT_PASSWORD (enables HTTP Basic auth on every route, including the WebSocket handshake), and/or
    • front it with an authenticating reverse proxy (Caddy + forward-auth, oauth2-proxy, Authentik, …), and/or
    • keep the published port bound to loopback / a private network only.
  • The server logs a loud warning at startup when it is listening on a non-loopback address without WT_PASSWORD set.
  • Each session's recent output (200 lines) is kept in the browser's localStorage by default so a reloaded tab does not refill over the wire. It is readable from that browser without passing WT_PASSWORD and outlives the tab; set WT_PERSIST_SCROLLBACK=false on a shared device or where storing command output at rest is unacceptable. See Persisted scrollback.
  • DNS rebinding reaches even loopback binds through your own browser: an attacker's page makes its hostname resolve to this server, and same-origin checks then pass because Origin and Host agree. Set WT_ALLOWED_HOSTS to the exact hostnames you browse to (rejects every other Host), or set WT_PASSWORD (the attacker's page cannot present credentials). The server warns at startup when neither is set.

Built-in Basic auth is a convenience for simple setups; a reverse proxy with real identity is the recommended posture for anything internet-facing. The process runs as the container user (root by default); restrict it with a non-root WT_CMD target, a read-only root filesystem, dropped capabilities, and a scoped work directory as your threat model requires.

What it does

It starts one command per terminal tab in a real PTY and streams that terminal to a browser: full VT screen buffer, scrollback, mouse, colours and clickable hyperlinks, driven by touch on a phone as well as a keyboard on a desktop. Tabs live on the server, so closing the page does not kill what is running, and reopening it reattaches to the same terminals from any device.

It is deliberately thin. The terminal itself is two shared libraries (the engine and its reference UI); this repo is one Go file that starts the PTY, serves the bundled front end, and applies the security posture described above.

Run

compose.yaml in this repo is a working example: loopback-bound, password set, a work directory mounted, and init: true. Copy it and adjust.

Or as a one-shot run:

docker run --rm --init -p 127.0.0.1:7681:7681 \
  -e WT_PASSWORD=changeme \
  -v "$PWD":/work -e WT_WORKDIR=/work \
  ghcr.io/cplieger/web-terminal-server

Open http://127.0.0.1:7681. Both examples bind the published port to loopback and set a password; adjust for your environment.

--init / init: true is required, not cosmetic. Whatever WT_CMD runs can fork a child that outlives its own parent, and the kernel reparents that orphan onto PID 1. This server waits only for the processes it started itself, so with no init it is PID 1 and every orphan stays a zombie for the container's lifetime. Docker's --init puts a small reaper there instead, which owns nothing anything else is waiting on. The server logs a warning at startup when it finds itself running as PID 1.

Naming terminals

Each terminal tab is labelled automatically: whatever is running in it (the foreground command), or the directory it sits in when the shell is idle, or the window title the program set for itself. Right-click a tab (press F2, or double-click it) to type your own name instead, which then sticks for the life of that terminal and shows on every device you have the page open on. The same menu offers Use automatic name to remove it again.

Names live on the server, not in your browser, so they survive a reload and are the same in every window.

Persisted scrollback

On by default. Set WT_PERSIST_SCROLLBACK=false to turn it off.

What it does: the browser keeps the newest 200 lines of each session, so a reload asks the server only for what was printed while the page was gone. Without it the terminal comes back holding nothing and pulls the whole retained scrollback back over the wire — you see the history filling in, and on a phone that is the normal case rather than an edge case, because iOS discards backgrounded tabs under memory pressure and returning to one re-runs the page. A warm reconnect and switching between tabs in one page already replay nothing, so this only changes the fresh-load case.

What it stores, which is the reason there is a switch at all: up to 200 lines of each session's output, in this origin's localStorage, and at most about 1 MB in total across every session. That is readable from that browser without reaching this server and without passing WT_PASSWORD, and it outlives the tab that produced it — an entry is deleted when you close its terminal, and otherwise after seven days. WT_CMD decides what ends up in there.

Most ways to read it also hand over a live shell, so the snapshot is rarely the weakest thing available. The exception worth knowing is a window where the snapshot is readable and the shell is not: a laptop off the VPN, a stopped container, an expired credential. Turn it off on a shared or borrowed device, or where storing command output at rest is not acceptable.

Nothing is ever sent anywhere: the server neither reads nor receives these snapshots, and it does not know whether a browser kept one. No permission prompt is involved — localStorage needs none — and a browser that blocks site data, or a private window, simply restores nothing and replays over the wire as before.

Restored content is checked against the running server on the first reconnect and cleared if it came from a previous run, which covers the confusing case: a restarted server numbers its output from the beginning again. If that session is already gone — which is what a restart usually leaves — the restore is discarded outright rather than shown behind a “Session ended” banner.

Configuration reference

All configuration is via environment variables. Where the binary and image defaults differ, the Default column shows them as binary / image.

Variable Description Default
WT_ADDR Listen address. The binary defaults to loopback; the image must listen on all interfaces. The baked healthcheck derives its port from this value and probes 127.0.0.1, so changing the port is safe but pinning the bind to one non-loopback interface makes the container report unhealthy while serving normally. 127.0.0.1:7681 / :7681
WT_LOG_LEVEL Log verbosity: debug, info, warn, or error (case-insensitive; slog offset syntax like warn+1 also parses). An unparseable value falls back to info with a startup warning. info
WT_CMD Command to run in the PTY, whitespace-split (use a wrapper script for complex commands). /bin/bash
WT_WORKDIR Working directory for the command. Must be an existing directory if set. (process default)
WT_SCROLLBACK Lines of history the server retains per session — how far back a user can scroll, and what a reconnect can replay. Kept in memory and grown as history is produced, so a large value costs nothing until a session actually reaches it: to say "never truncate", set a number no session will hit. 0 retains nothing beyond the live screen. Values between 1 and 2000 are raised to 2001 with a warning, because at or below the depth a reconnect replays in full there is nothing left to page for, so the browser falls back to holding its whole buffer — asking for less server history would cost the phone more. This is the terminal engine's own variable, shared verbatim with every app built on it, which is why this server holds no default of its own. 100000
WT_PERSIST_SCROLLBACK Keep each session's recent scrollback in the browser's localStorage, so a reloaded or browser-discarded tab resumes with a delta instead of refilling its whole buffer over the wire. Set false to turn it off — see Persisted scrollback. true
WT_IDLE_REAPER Go duration (e.g. 30m); when > 0, idle sessions are reaped after this long. (unset → disabled)
WT_USERNAME Basic-auth username (only used when WT_PASSWORD is set). admin
WT_PASSWORD Basic-auth password. When set, every route (including /ws) requires it. (unset → no auth)
WT_ALLOWED_HOSTS Comma-separated exact hostnames/IPs the server answers for; any other Host header is rejected (the DNS-rebinding guard; see the security warning above). The carve-out needs loopback on both ends — a loopback client address and a loopback Host — so the image healthcheck and a same-host curl keep working while a forged loopback Host from a remote peer does not. Any other name you browse to must be listed. Malformed entries are dropped with a warning; a list whose entries are all malformed fails closed, rejecting every non-loopback request. (unset)
WT_TRUSTED_PROXIES Comma-separated reverse-proxy CIDRs / bare IPs whose X-Forwarded-For the access log trusts to resolve client_ip. See Client IP logging. (unset → socket peer)

Endpoints: / (UI), /ws?session=<id> (per-session terminal WebSocket), /api/sessions (create/list/close), /api/sessions/{id}/pinned-title (name a terminal; PUT to set, DELETE to go back to the automatic name), /api/sessions/events (status SSE), /healthz (readiness).

Volumes
Mount Description
(any path) Nothing is required. Mount whatever the command needs to reach and point WT_WORKDIR at it; the examples above mount the current directory at /work.
Ports
Port Description
7681 HTTP + WebSocket. Serves the UI, the session API and the terminal socket. Change the listen address with WT_ADDR; the healthcheck follows it.

Startup failures

A startup failure produces exactly one ERROR line, web-terminal-server exited with error. The remedy is in its error field, and a stage field names which step failed:

stage What failed
config The WT_* environment is invalid: a missing or unreadable WT_WORKDIR, an unparseable WT_PERSIST_SCROLLBACK or WT_SCROLLBACK.
static The embedded front end or its Content-Security-Policy is unusable. A build defect, not a setting: no environment change fixes it.
listen The address in WT_ADDR could not be bound.
serve The HTTP server exited with an error while running.
unknown A failure nothing attributed.

Key log queries and alert rules on stage rather than on the message text: the values are a stable contract with a test behind them, the prose is not.

A rejected environment value is never echoed into that line. Only the variable's name and the accepted shape appear, because a compose interpolation mistake is what puts a credential on a variable in the first place.

Client IP logging

The access log records a client_ip per request. By default (WT_TRUSTED_PROXIES unset) it logs the direct socket peer and ignores any X-Forwarded-For header, so the logged IP cannot be spoofed; that's the correct choice when the server is directly exposed. Behind a reverse proxy the socket peer is the proxy, not the user, so set WT_TRUSTED_PROXIES to the proxy's address(es), a comma-separated list of CIDRs or bare IPs (e.g. WT_TRUSTED_PROXIES=10.0.0.0/8,192.0.2.10), and the log resolves the real client from a trusted X-Forwarded-For. Only a request whose socket peer is inside the set has its X-Forwarded-For trusted (spoof-safe); a malformed entry is logged and skipped rather than aborting startup. Log timestamps are UTC regardless of the container's TZ, so lines stay zone-stable for ingest.

A terminal that successfully attaches (the /ws WebSocket handshake) gets no line: the handshake ends the HTTP exchange, so the line could only be written when the socket finally closes, reporting a session-long duration and a status the server never sent. Every attach ATTEMPT is recorded separately, before the handshake runs, with a truncated session id, the client IP and the request id — that record is the audit trail for a socket that presents a session credential. A handshake that is refused is also logged with its real status — a rejected Host, a cross-origin request, missing credentials, a plain HTTP request with no upgrade headers — so that is what to grep when a browser cannot attach.

The session id in /ws?session=<id> is a capability: holding it is enough to attach to that terminal. This server keeps it out of its own logs (the access log records the route template for session paths, and the attach record truncates the id), but a fronting reverse proxy logs full request URIs by default and would capture it in the clear. Drop or redact the /ws query string in the proxy's own access log.

Healthcheck

The image ships a HEALTHCHECK that probes /healthz on loopback every 30s, after a 15s start period. /healthz answers 200 {"status":"ok"} once the listener is bound and 503 during startup and the graceful-shutdown drain, so a load balancer stops sending traffic while the server is draining.

Two details worth knowing. The probe derives its port from WT_ADDR, so moving the listener keeps it working. And when WT_PASSWORD is set the probe authenticates with WT_USERNAME/WT_PASSWORD through a curl config file on stdin rather than a command-line flag, so the password never appears in the container's process list.

It is a readiness signal, not liveness: nothing restarts the container on an unhealthy state, so a problem surfaces as unhealthy in docker ps without a restart loop.

Dependencies

Dependency Source
Debian trixie-slim Base image, pinned by digest. apt-get upgrade runs at build time so security updates ship with each release.
github.com/cplieger/web-terminal-engine The Go PTY/VT session engine and its TypeScript browser renderer.
@cplieger/web-terminal-ui The touch-first browser UI served to the client.
github.com/cplieger/webhttp Server HTTP plumbing: access logging, middleware chain, security headers, static serving, rate limiting.
github.com/cplieger/envx, slogx Typed environment parsing and the fleet-standard slog setup.
Monaspace Neon NF The terminal webfont, fetched at build time and digest-verified per face.
Go toolchain, TypeScript compiler Build-time only, both digest-verified per architecture.

Every version is pinned, and every build-time download is checked against a recorded sha256, so a compromised registry cannot change what the image contains. Updates arrive as automated pull requests and ship through a fresh image build.

The web-terminal family:

Apps built on the same engine:

  • vibekit: a chat-first browser front end for the Kiro CLI (chat history, MCP, editor, git/forge workflows).
  • web-terminal-kiro: a touch-first, multi-tab browser terminal wired to the Kiro CLI (kiro-cli), on desktop or phone.

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md for the conventions and how to run the checks locally.

Disclaimer

This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.

This project was built with AI-assisted tooling using Claude, GPT, and Kiro. The human maintainer defines architecture, supervises implementation, and makes all final decisions.

License

MPL-2.0. See LICENSE.

Documentation

Overview

Command web-terminal-server is a thin, generic web terminal: it runs a configured command in a PTY and serves the @cplieger/web-terminal-ui front end over HTTP + WebSocket, using github.com/cplieger/web-terminal-engine/v4.

SECURITY: this is a remote shell. Anyone who can reach the listen address and pass auth (if any) gets an interactive process running WT_CMD with this server's privileges. It binds loopback (127.0.0.1) by default; only expose it on a public interface behind an authenticating reverse proxy, or set WT_PASSWORD. See README.md.

Directories

Path Synopsis
scripts
wirecheck command
Command wirecheck asserts wire-protocol compatibility between the Go server half (the web-terminal-engine module go.mod pins) and the served TS client half (the Dockerfile-ARG-pinned npm artifact).
Command wirecheck asserts wire-protocol compatibility between the Go server half (the web-terminal-engine module go.mod pins) and the served TS client half (the Dockerfile-ARG-pinned npm artifact).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL