Repository navigation
Technical Reference
Browserland (codename webterm, still the name of the Python package and its
directories) is a self-contained web terminal system: headless PTY agents + a
WebSocket broker, speaking Browserland's own web-terminal producer protocol. The
name evokes a place — a little world inside your browser where a whole fleet of
terminals and AI coding agents live, are launched, and are driven from a single
tab. (webterm remains the Python package/module name.) The protocol is
deliberately small: any producer that speaks these JSON frames over a single
WebSocket can register with the broker.
┌─────────┐ binary ANSI + JSON ┌────────┐ /ws?session=<id> ┌─────────┐
│ agent │ ──────────────────▶ │ broker │ ──────────────────▶ │ browser │
│ (PTY + │ ◀────────────────── │ :4445 │ ◀────────────────── │ xterm.js│
│ ConPTY/ │ input/resize/ └────────┘ input/paste/resize └─────────┘
│ openpty)│ snapshot_please
└─────────┘
# broker (default 127.0.0.1:4445)
python -m webterm.broker
# an agent running cmd.exe, registered with the local broker
python -m webterm.agent -- cmd.exe
# then open http://127.0.0.1:4445/ and click the session (or "new terminal")Linux:
./launchers/run-broker.sh # broker
./launchers/run-agent.sh -- bash -l # agent| Path | What |
|---|---|
webterm/protocol.py |
the ONLY place the JSON frame shapes live |
webterm/agent/ |
headless producer: PTY backend + ring buffer + OSC title sniffer + reconnecting WS client |
webterm/agent/backends/linux_pty.py |
pty.openpty + Popen + loop.add_reader; TIOCSCTTY so Ctrl-C works |
webterm/agent/backends/win_conpty.py |
Windows PTY via low-level winpty.PTY + reader thread (Proactor loop has no add_reader for pipes). Backend auto-selection: ConPTY silently drops the 0x03 → CTRL_C_EVENT translation when the hosting process has no console (verified empirically — exactly the headless cases this agent exists for), so on auto (and forced conpty) the agent first acquires a hidden console (AllocConsole + SW_HIDE) and re-enables Ctrl-C (SetConsoleCtrlHandler(None, FALSE), undoing CREATE_NEW_PROCESS_GROUP's disable — #25), and detached agents then run ConPTY; auto falls back to WinPTY only when acquisition or the re-enable fails, and winpty forces the legacy backend without acquiring a console. |
webterm/agent/snapshot/raw.py |
tier-1 snapshot: ESC[0m ESC[2J ESC[H + ring replay |
webterm/agent/snapshot/pyte_snap.py |
tier-2 (optional, --snapshot-mode pyte): replay ring through pyte, render the settled grid |
webterm/broker/ |
Sanic app: desktop UI page, /ws relay, /browserland producer WS, /sessions, profiles-only POST /launch
|
launchers/ |
venv-bootstrapping run scripts for both OSes |
python -m webterm.agent [opts] [--] command...
--broker-url URL $BROWSERLAND_BROKER_URL > flag > ws://127.0.0.1:4445/browserland
--auth-token TOK $WEB_TERMINAL_TOKEN; appended as ?token= (REQUIRED
for every broker since #142, loopback included)
--cols/--rows initial PTY size (default 80x24)
--title T initial title (default: command basename)
--window-id N pin the session id (default: random 48-bit)
--ring-bytes N snapshot ring cap (default 262144)
--snapshot-mode raw|pyte
--cwd DIR
The agent's exit code is the child's exit code. While the broker is down
the PTY keeps running; the client reconnects with exponential backoff
(0.5 s → 10 s cap, ×2 per failure, reset on success) and re-hellos with the
current title/dims. Missed bytes are not replayed — the browser's attach
triggers snapshot_please, which heals from the ring.
psutil is an optional, best-effort dependency (pip install -e ".[procs]"),
not declared in core deps. It powers the task-manager process list
(enumerate_procs), the foreground-agent badge (foreground_command), and
live-cwd tracking (cwd) — each degrades to empty/None without it. Destroying
a window also prefers the psutil path (identity-checked create_time guard),
but the Linux backend's kill_proc_fallback kills the shell's whole POSIX
session by SID (the shell is its own session leader via start_new_session,
disjoint from the agent's session) when psutil is absent, so "destroy window"
works either way. Windows without psutil still returns psutil_unavailable
for destroy (no fallback yet).
python -m webterm.broker [--host 127.0.0.1] [--port 4445] [--config PATH] [--headless]
--headless (or config "serve_ui": false, default true) serves the full
JSON/WS API but not the desktop page or the in-app Help — GET / returns
200 {"ui": false}, /help-corpus.json 404s, and both UI constants
(INDEX_HTML, HELP_CORPUS) are never assembled (#87). --headless overrides
the config key (like --host/--port); there is no --no-headless. GET /info
reports the active mode as serve_ui (the one additive change to a JSON route);
existing JSON/WS behavior is otherwise unchanged in either mode.
Config (broker_config.json, path overridable via $WEB_TERMINAL_CONFIG;
see broker_config.example.json): auth_token, plus agent.profiles for
/launch. Profiles only — /launch accepts
{"profile": "cmd", "cols": 120, "rows": 32, "title": "..."} and never a
client-supplied command/cwd/env. Responses: 200 registered, 202 spawned
but no hello within 10 s, 400 unknown profile, 401/403 auth, 429
too many pending, 500 agent exited early.
GET /update/check?refresh=1 re-asks GitHub through the daily cache; the 30-minute poll never sets it, and only a literal 1 counts. Because a forced refresh bypasses the TTL it bypasses the quota strategy with it, so the broker floors it at one per 60 s and caps it at six per rolling hour, leaving most of GitHub's 60/hour-per-source-IP for everything else on that machine. An active rate-limit negative cache outranks the button entirely — the reset GitHub named in a header is honoured, not clicked through. Admission is decided and reserved inside the same lock the fetch holds (checking before the lock would let a queue of requests each pre-authorise themselves and then fetch in turn), and attempts are stamped before the request goes out, since a failed fetch spends the same quota as a successful one. A refresh that finds a newer publish than the one it queued behind coalesces rather than re-asking, tracked by a publish serial read before the lock. A refused refresh answers 200 with the cached result plus refreshed: false and refresh_refused: {reason, retry_after_s} — never an error, and never a bare 200 a client could render as "just checked".
POST /update/apply applies the previewed upstream commit, then exits with code 75 so the supervisor restarts into the new code. It is manual-trigger only — no schedule, no timer, no auto-install. Requires all three of update_check_enabled, update_apply_enabled, and restart_enabled to be true. Each resolves independently: a key present in broker_config.json (either true or false) owns that one gate and locks it against the GUI; an absent key leaves the gate to a sidecar (webterm_update_policy.json) written by POST /update/policy — the desktop's one-click consent when the update mod is turned on grants whichever of the three the config hasn't already claimed, and the Update window's "Allow this broker to update itself" row grants apply + restart together afterward. POST /update/policy takes any subset of the three keys; keys it does not name keep whatever the sidecar already had, so two operators granting different gates never clobber each other. A corrupt sidecar fails every gate it would otherwise decide closed, never through to a default.
The route takes {"target_sha": "<40-hex>"} — exactly the commit the UI previewed in the last successful check. The server re-proves every precondition fresh:
- The target commit is not some random hash — it is the one the latest check named as ahead of / current-with upstream.
- The working tree is clean (no staged/unstaged changes; uncommitted work must be committed or stashed).
- No local commits would be discarded (if the check said "3 behind", applying is safe; if it said "2 ahead / 3 behind", applying would discard work).
- Dependencies match or are acceptable (a dependency added/removed by the update is reported so the operator can decide whether to install/uninstall first).
- Restart is possible (the gate is on, the supervisor exists, the mechanism is available).
The git phase lives in webterm/broker/update.py's marked mutation section: git fetch <explicit https URL> <ref> (never git pull, never a remote name — a fork's origin must be irrelevant), then git merge --ff-only <sha> with hooks disabled. Objects are fetched with a 120-second timeout; the merge with a 60-second timeout. Stderr is captured for reporting; the report names every locked file on Windows, bounded to 2000 bytes.
Failures are reported accumulating every reason — the UI shows all unmet preconditions in one pass rather than trial-and-error. The response is 202 with a last_deploy section surfaced in the next /update/check so the UI can report the outcome.
The broker that was running the old code exits and is replaced. A rollback is automatic: if the new broker never comes up (supervisor restarts it, but it exits again before a worker-ready timeout), the supervisor automatically reverts to the recorded prior commit sha (held in deploy.journal beside the checkout). The outcome (rolled-back, deploy-failed, etc.) rides in the next check response under last_deploy.outcome, visible to the operator.
Agents survive the restart and reconnect to the new worker, but terminals do not re-execute: they keep running the old code they imported. The UI offers a Fresh terminal button to spawn a new one. Agents (AI coding assistants) also survive, but any in-memory state (context, plan, accumulated tokens) is lost — the restart is opaque to them, so they reconnect to an empty board.
The deploy.journal records every apply attempt (sha before, sha after, outcome, why it failed if it did) outside the checkout, so git gc cannot erase it. Rollback success is proved by a changed bootId (reported in /info); rollback failure is kept as rollback-impossible and requires manual repair.
python -m webterm.broker is now a supervisor that spawns the actual server as a worker subprocess. The launcher scripts (bash and PowerShell) and the systemd unit all use exec to start the supervisor, making it the main process — there is no wrapper loop. When restarted from the UI, the supervisor stays alive and re-spawns the worker, a broker-generation restart: the server process is replaced with fresh code, but agents reconnect to the new worker and survive. It is not a service restart — the launcher preamble and systemd unit environment are not re-run.
Restart is opt-in, resolved the same per-key way every update gate is: if broker_config.json names restart_enabled (either true or false), that key owns the gate and only editing the file can move it; if it is absent, the gate is the desktop's to grant, via the Update window's "Allow this broker to update itself" row (which grants apply_enabled and restart_enabled together — see the update mod's own docs). A restart from the UI drains gracefully (stops accepting new work, waits for in-flight critical writes to finish or time out, disconnects idle sessions), and the confirm dialog reports session continuity: guaranteed (agents that survive), at_risk (lost), and unknown. A per-boot cooldown (restart_cooldown_seconds, default 90, 0 disables — also config-file only) refuses back-to-back restarts; 90 is deliberately longer than the supervisor's 60-second budget window, so deliberate restarts can never exhaust the crash budget.
The mechanism is a sentinel file and exit code 75: the worker exits 75 (normally reserved for another purpose — this supervisor owns it now) and writes a nonce-matched intent sentinel. The supervisor relaunches only if the sentinel matches, refuses any exit-75 without a sentinel, and treats an unarmed 75 as a crash. A restart can happen from systemd (Restart=always or on-failure, not on-success), a Windows scheduled task (Stop-ScheduledTask kills abruptly — graceful drains do not complete), or python -m webterm.broker by hand (no restart). The supervisor has a restart budget — five relaunches inside 60 seconds with exponential backoff (0.5 s initial, doubling per crash, clamped at 30 s, reset only when a worker stays up 10 s). A crash loop that exhausts the budget exits with a non-zero code; systemd's own StartLimitAction can then step in.
GET /info reports restart.available (can we restart now), restart.mechanism (supervisor / systemd / none), restart.bootId (this process's id — changes on restart, lets a client confirm it happened), and session continuity. A client confirms a restart by watching bootId change.
There is one build id in this project: webterm.build_version() — the package
version from webterm/__init__.py (the single source; pyproject.toml
declares dynamic = ["version"] and reads that attribute) plus the git short
hash when running from a checkout, e.g. 0.8.0+ba4b62e. It is derived from the
package's own directory (never the process cwd, so a wheel installed inside an
unrelated repo cannot report that repo's commit), cached per process, and never
raises.
It rides the agent hello, GET /info and GET /mcp/info — and it is baked into
the served desktop page:
<meta name="webterm-build" content="0.8.0+ba4b62e">A broker serves the page it assembled at import, so a git pull changes
nothing until the process is restarted. That is the gap this closes:
curl -s http://host:4445/ | grep webterm-build
git -C /path/to/checkout rev-parse --short HEAD
The stamp's +hash matches → the running process is the pulled code; it does
not → a restart is still pending. The stamp describes the running process,
not the checkout on disk, exactly because build_version() is cached at import
and never recomputed per request.
Read it for what it is: the revision HEAD pointed at when that process first
asked. It cannot see uncommitted edits (there is no dirty marker — two different
dirty trees would share a hash, which is a worse signal than none), and if a
pull lands while a broker is running, modules imported before and after it
come from different revisions and no single stamp can say so. A caching reverse
proxy in front of GET / will also happily serve you an old stamp.
It is a <meta> in the head and deliberately not a value inside the page's
one inline script: script-src authorizes that script by sha256 of its exact
bytes (see Auth model), so a per-commit string in there would
change the CSP hash on every commit. Script that wants the value reads the tag —
document.querySelector('meta[name="webterm-build"]').content.
A token is required on every surface, on every interface, always (#142) —
no loopback exemption, no opt-out. Resolution (never returns nothing):
$WEB_TERMINAL_TOKEN → config auth_token → the webterm_token.json sidecar
beside the state store → mint secrets.token_urlsafe(32) into it. Compared
with hmac.compare_digest. python -m webterm.broker --print-token reports it
without minting or starting a server.
Loopback was never a sound exemption: tailscale serve in front of a
127.0.0.1 bind (the topology Setup-and-Onboarding recommends) makes every
tailnet request arrive from loopback, and any page in the user's browser
reaches loopback too. Upgrading a tokenless install is a breaking change —
see Upgrading.
How the token travels (#144). HTTP sends it as Authorization: Bearer, never in the
query string. A URL credential leaks where a header does not: any script on the page can
read the full URL out of performance.getEntriesByType('resource'), a DevTools HAR export
carries it into a bug report, and a reverse proxy logs it. There is deliberately no
client function that builds a token-bearing HTTP URL, so one cannot be reintroduced by
accident — hostFetch(host, path, opts) is the only way to call the API.
Two places still carry ?token=, both unavoidable and both deliberate:
-
WebSocket dials (
/ws,/control,/browserland). The browser WebSocket API cannot set request headers on the handshake, sohostWsUrlappends the token. Closing this needs a short-lived connect-ticket scheme, not a refactor. -
The
?token=deep link (http://host:4445/?token=…). It is how a token reaches a fresh browser at all; it is adopted into localStorage and scrubbed from the address bar viahistory.replaceStateon load.
So this narrows the exposure from every request to the handshake and the first load — it
does not eliminate it. Operationally: an Authorization header makes a cross-origin
request non-simple, so remote hosts pay an OPTIONS preflight; the broker answers every
one and sets Access-Control-Max-Age: 86400, making it one round trip per host per day
rather than per request. ACAO: * stays legal because a header set explicitly by
fetch() is not a credentialed request in the CORS sense (that needs
credentials: 'include'), which is also why a wrong token still returns a readable 401
instead of an opaque failure — that is what keeps the login overlay working. If you
front the broker with a reverse proxy, it must forward the Authorization header; a
proxy that strips it makes every host look like a wrong password.
The mint is O_CREAT|O_EXCL (0600 on POSIX; Windows inherits the directory
ACL), not an atomic replace: two brokers racing on one state dir both see no
file, and last-writer-wins would leave the loser running a token that is not
the one on disk. The O_EXCL loser re-reads and adopts the winner. An unwritable
directory yields an ephemeral token — the broker still starts, but warns on
every boot that it changes on restart and --print-token cannot recover it.
| Surface | Rule |
|---|---|
GET /, GET /help-corpus.json
|
unauthenticated. The token is typed into that page and auth is query/header-only with no cookies, so gating the document deadlocks the bootstrap — every reload, bookmark and new tab would 401 forever. Neither carries host- or session-derived data. Headless, GET / is 200 {"ui": false}, so health probes keep working. The corpus is public but auth-sensitive (#173): with no token it is the wiki + shipped-mod corpus alone, exactly what it was before #163; the sections contributed by installed mods — their help text, their manifest label/icon, and hence the list of installed ids — are merged in only for a caller holding the token. Same request_token_ok as every gated route, answering with a smaller 200 instead of a 401, plus Cache-Control: no-store and Vary: Authorization so no cache can hand one audience the other's body. |
GET /vendor/*, GET /mods/<id>/<gen>/<name> (#163) |
unauthenticated, and forced rather than chosen: the browser needs the vendored xterm to render the login page, before any token exists, and a <script src> cannot carry an Authorization header (?token= is structurally banned by #144). Both serve from an in-memory allowlist dict, so a client-supplied name can never reach the filesystem. Consequence: an installed mod's source and styles are publicly readable, exactly as GET / already carries every shipped mod's source — but reaching one takes the id and the generation and the file name, and #173 stopped the help corpus from handing out that first ingredient. Neither ingredient is a broker secret, though: <gen> is a content hash of the package, so someone holding a publicly distributed mod's bytes recomputes it and can confirm that mod is installed here (200 vs 404). #173 stops the corpus enumerating installed ids; it cannot hide a mod you already know to ask for by name. help.md is not servable here at all. |
OPTIONS preflights |
unauthenticated by design (they carry no credentials). Explicit routes, because route resolution happens before request middleware. |
WS /browserland (producers) |
token required, loopback included. Was the one gate the token never covered — and WebSockets are not CORS-gated, so any website could dial ws://127.0.0.1:4445/browserland, re-register a live window_id (kicking the real agent off with 1012) and inject fabricated terminal output. Refusal is a post-upgrade WS close 4401 (an HTTP reject would surface as an opaque 1006). A re-register whose host and nonzero pid match the entry it replaces now keeps that window's MCP access override instead of falling back to the broker default; that match is a collision heuristic, not a security boundary (both are self-reported), and the producer token is the boundary. |
POST /launch |
token required — never an open RCE on any bind. |
WS /ws, WS /control, GET /sessions, GET /profiles
|
token required (?token=, ?auth=, or Authorization: Bearer). Always 401 auth_required, never 403: the login overlay and the taskbar host chips pop on 401 only. |
GET/POST /profiles/config, GET /profiles/detect (profile editor, #70) |
browser token, same as /file/* and /mcp/config. Full commands are browser-realm only; /profiles and /mcp/profiles stay names-only. |
GET /status/fetch (AI-provider status proxy, #112) |
browser token, same as /info and /state. The broker's only outbound HTTP: an allowlist of AI-provider Atlassian Statuspage hosts, reached by provider id (the client passes ids, never a URL — unknown ids are dropped, an all-unknown request is 400). Each fetch is https-only, no-redirect, no-proxy, 200-only, 512 KiB-capped, 4 s timeout, with a 60 s per-id cache; any failure degrades to an unknown row (never blocks the UI). Privacy: enabling the (default-off) aistatus mod is what turns this on — the broker's egress IP then becomes visible to those status hosts, so it ships disabled until you opt in. |
| CORS (JSON API) |
Access-Control-Allow-Origin: * unconditionally on every response, including the 401 — lets the multi-host UI on another broker's origin read this one, and without it a cross-origin login probe surfaces as a fetch TypeError ("wrong password" indistinguishable from "host down"). Auth is token-in-query/header and never cookies, so * grants no ambient credential; the real gate is the token on every route. |
| Response headers |
Referrer-Policy: no-referrer (the desktop URL carries the token, so an outbound link must not leak it in Referer), X-Frame-Options: DENY + CSP frame-ancestors 'none' (GET / is public so login can bootstrap, but an attacker page must not be able to iframe the real UI and clickjack a browser that already holds a token), and CSP script-src — see below. |
Third-party code (#143, #146). The page used to pull xterm from jsdelivr and, lazily, CodeMirror from esm.sh — third-party code executing in the same origin that holds prefs._hosts[].token for every configured host, tokens that gate /launch and host-wide /file/*. Both are now vendored, and no third-party origin executes in the page at all:
-
xterm is vendored into
webterm/broker/vendor/and served by the broker at/vendor/*(public, likeGET /— the browser needs it to render the login page, before any token exists). There is no CDN to compromise, no SRI hash to keep in sync, and the terminal now works offline, which it never did before. The bytes are the exact published npm files, pinned by sha384 intests/test_vendor_assets.py; an upgrade is a commit that changes both. Served from an allowlist dict, so a client-supplied name can never reach the filesystem. -
CodeMirror is vendored into
webterm/broker/vendor/codemirror/and served at/vendor/codemirror/*by a second route with a literal segment (so the lookup is still one dict get on a prefixed key — a name can't express a path). The text editor works offline too. See below for why it took its own generator. -
script-srcallows only'self'and a'sha256-…'for the page's single inline<script>. The hash is computed at startup from the assembledINDEX_HTMLitself (ui.inline_script_hash), so it tracks the bundle automatically and needs no'unsafe-inline'— meaning an injected inline script cannot execute either. Nothing else is set (nodefault-src/style-src/connect-src): those would have to enumerate every inline style, thedata:favicon,blob:download URLs and every federated host, each a way to break the app for no gain here.
Why CodeMirror needed a generator (#146). xterm was four self-contained files with exact-pinned URLs — download, hash, commit. CodeMirror 6 is ~116 modules across 40 npm packages that must share one instance each of @codemirror/state, view and language; a second concrete build of state throws and drops the editor to a plain <textarea>, while a second view or language is silent — syntax highlighting just stops. That is why CM_VER in mods/editor/codemirror.js uses semver ranges: esm.sh collapsed every range onto one build at request time. Mutable URLs meant nothing could be hashed, which is why esm.sh stayed in script-src after #143.
python -m webterm.broker.vendor_codemirror moves that guarantee from request time to generate time. It parses CM_VER (still the single source of truth for what the editor loads), crawls the graph from esm.sh keying every module by its final resolved URL, rewrites each import specifier to a relative sibling path, and refuses to write anything if any package appears twice. Run it by hand on upgrade; --check re-verifies the committed tree offline. Two details worth knowing:
- It only rewrites the module prologue, not the whole file.
@codemirror/lang-javascriptships completion snippets whose payload is literal JavaScript source (p('import {${names}} from "${module}"…')) — a file-wide regex matches inside that string and corrupts it. Static imports are top-level-only and esbuild hoists them, so the prologue is where they all are; the generator then asserts nothing package-path-shaped survives past it. - The first run found
autocomplete,lang-htmlandlang-javascripteach loading twice — our exact pins had drifted behind what the transitive^ranges resolved to, so esm.sh was serving both. Those three became ranges. The assertion that caught it now runs intests/test_vendor_assets.pyagainst the committed graph.
Per-file sha384s live in the generated vendor/codemirror/manifest.json (which is also the served allowlist); only the manifest's own hash is pinned in the test file, so an upgrade is one hand-updated constant. Like the xterm pins, that is change-control friction, not a security guarantee — it makes a silent change impossible, not a deliberate one.
Recordings are stored gzipped (#159). A recording is JSONL carrying base64 PTY output —
about the most compressible thing the app produces, and an always-on capture rolls a fresh
50 MiB segment forever. New recordings land as <id>.blrec.gz (measured ~8x smaller);
<id>.blrec keeps meaning an older uncompressed file and is never rewritten. The suffix
is the encoding — nothing sniffs content, so a corrupt .gz reports as a corrupt gzip
rather than being retried as JSONL. Each uploaded chunk is compressed as its own gzip
member, which keeps appends streaming and commit a plain os.replace; concatenated
members are valid gzip and Python/GNU tooling reads them transparently. GET /recording
still serves plain JSONL on the wire, deliberately: HTTP client decoders commonly stop
at the first member (httpx does), so passing the stored bytes through under
Content-Encoding: gzip would silently truncate multi-chunk recordings. Disk was the
growth problem; the wire is unchanged.
Auditing recordings for secrets (#145). A recording captures the terminal's output
byte-for-byte, so anything the terminal echoed is in it — a secret pasted onto a visible
command line, an API key printed by a config dump, or this broker's own token if someone
ran --print-token while recording. Recordings are durable and downloadable, so:
python -m webterm.broker --scan-recordings # 0 = clean, 1 = found, 2 = incomplete
python -m webterm.broker --scan-recordings --json # machine-readable
python -m webterm.broker --scan-recordings --secret <OLD_TOKEN> # rotated tokenIt resolves the live auth_token and mcp_token read-only (auditing must never mint
one — that would search for a value the broker isn't even running) and streams each file,
base64-decoding d before searching. That decode is the whole point: a plain
grep <token> *.blrec finds nothing even when the token is present and returns a
confident false all-clear. Output payloads arrive in arbitrary PTY chunks, so the scanner
carries a len(secret)-1 byte tail across events — a secret split over two (or twenty)
events is still found, and one that straddles a resize/gap event is too. It scans both
encodings; a compressed recording it could not open would be a live secret that quietly
stopped being findable, so a file that fails to decompress is reported as an error
(exit 2, incomplete) and never skipped into a clean result. By hand, the compressed
equivalent of the futile grep above is zgrep / gzip -dc … | grep — equally futile,
and for the same base64 reason.
Its limits are printed on every run, including clean ones, because a tool like this
recreating the false all-clear would be worse than not having it: it finds a secret only
where it appears as contiguous bytes. A secret the terminal broke up — interleaved with
colour/cursor escapes, redrawn by the shell as you typed, echoed a character at a time —
is not found, and a rotated secret is only searched for if passed with --secret. It is
read-only: recordings are archived artifacts and nothing here rewrites one.
Tokens are passed to spawned agents via env only (never argv — visible
in process lists), and auth failures log only path + client IP (the token
rides in query strings — Sanic's access log is pinned off for the same
reason). The agent then removes WEB_TERMINAL_TOKEN before spawning the
user's shell, so a terminal cannot echo the credential that gates host-wide
file access and shell spawning.
An agent refused with 4401 backs off to the 10 s cap (the rejection arrives
post-upgrade, after the backoff has already reset, so the naive loop retries
at ~1 Hz forever) and logs one error naming $WEB_TERMINAL_TOKEN. It keeps
retrying rather than giving up: the token can come back without the process
restarting.
Browser login: the token doubles as the UI's password. The page is
served ungated; a login overlay probes /sessions and stores the token in
localStorage (per browser, per host). ?token=/?auth= URLs still
work as deep links — the token is adopted into localStorage and then
scrubbed from the URL via history.replaceState (behavior change from the
URL-persistence era: copied links no longer carry auth; ?session= deep
links survive the scrub).
Note: the broker pins app.config.AUTO_EXTEND = False. sanic-ext, when
merely installed, silently injects its own CORS middleware and an
unauthenticated /docs + /openapi.json; CORS here is hand-rolled and
token-gated instead.
Control Panel → Hosts lets the UI attach to sessions on additional brokers
(e.g. a WSL box over Tailscale). The browser connects directly to each
host (cross-origin fetch /sessions + ws://host/ws); hosts and their
passwords live per-browser in localStorage. Requirements:
- you need the remote broker's token (every broker has one — either
configured or minted;
python -m webterm.broker --print-tokenprints it) and a way in: either a non-loopback bind (plain http), or — recommended — a loopback bind fronted bytailscale serve/ an https reverse proxy. Settingauth_tokenexplicitly is worth it across a fleet so every host shares one password instead of a per-machine minted value; - both brokers must run this webterm version — a pre-CORS remote reads as a red "down" broker even when it's running;
- one scheme for the whole fleet — an https page fetching an http remote is blocked as mixed content, so cockpit + hosts must be all-https (preferred: unlocks secure-context features like clipboard image paste) or all-plain-http (see SETUP.md → Multiple machines over Tailscale).
A single broker's status chip is shown in the taskbar by default, even
healthy and local. Since the per-broker actions moved onto the (+)
menu's rows it is a pure indicator, so the browser-global
hostStatusChip setting can switch it to attention (drawn only while
some broker is auth-needed / down / lease — a broker the user HID does
not count) or never; hiding is a hide-broker-chip body class, never
an inline display, so the node stays put as the ws-pager's anchor and
eats no taskbar gap slot.
Four states: green ok / red down / amber password-needed / blue lease;
an ok/down chip toggles that host's window visibility, while auth and
lease chips are click-to-log-in / take-over. With two or more brokers
the chips collapse into one worst-state aggregate badge whose click
opens the start (+) menu, where each broker has a live status row with
the same per-host actions (the hide toggle keeps the menu open).
Window prefs are keyed per host; a down host never closes or re-dials
another host's windows.
Remote agents against this broker:
BROWSERLAND_BROKER_URL='ws://broker-host:4445/browserland' \
WEB_TERMINAL_TOKEN='...' ./launchers/run-agent.sh -- bash -lAny producer can register the same way:
BROWSERLAND_BROKER_URL=ws://host:4445/browserland?token=....
Install (for running and testing):
python3 -m venv .venv
.venv/bin/pip install -e ".[dev,pyte]"Zero-setup alternative: launchers/run-broker.sh / run-agent.sh
bootstrap a venv with the runtime deps on first run — fine for running,
but they don't install pytest, so use the editable install for testing.
Config: copy broker_config.linux.example.json to
broker_config.json (or point $WEB_TERMINAL_CONFIG at it). Default
profiles are bash (bash -l, the default) and sh (plain sh — the
escape hatch when login-shell rc noise is unwanted). A token is required on
every bind including loopback; set auth_token (or $WEB_TERMINAL_TOKEN)
to choose the value yourself, or let the broker mint one into
webterm_token.json and read it back with --print-token.
systemd: installable units live in launchers/systemd/
(webterm-broker.service, webterm-agent.service). Copy to
/etc/systemd/system/, edit User=, the /opt/web_terminal paths and
the token, then systemctl daemon-reload && systemctl enable --now ....
Caveats: the bash -l profile sources the service user's login profile
(use the sh profile if that produces noise), and /launch-spawned
agents are session leaders that survive broker restarts — they
re-register within ~10 s of the broker coming back.
Tests on Linux: python -m pytest tests -q → the full suite passes;
the Windows-ConPTY e2e suites skip on Linux. This
includes a real-POSIX-PTY suite (tests/test_linux_pty.py) that was
written blind on Windows and verified against a real Linux PTY before
deploying.
Producer → broker: hello (required first frame; same window_id
replaces), title, resized as JSON text; raw ANSI output and
snapshots as unframed binary. Broker → producer: input, resize (reply
resized), snapshot_please (reply one binary full redraw). Browser
attach: broker sends resized before requesting the snapshot. Snapshots
start ESC[0m ESC[2J ESC[H — deliberately no ESC c/ESC[3J, since
already-attached browsers receive them too — and end with a DEC-mode
re-assert postamble (?2004h/l + ?1h/l + mouse reporting, per the
agent's live sniffer; #138, #154) so a reloaded xterm.js recovers
bracketed-paste, application-cursor and mouse-tracking state. Mouse
reporting is two mutually-exclusive groups — tracking level
(9/1000/1002/1003) and extended encoding (1006/1016) — and within
each the postamble emits the resets first and the set last, because
xterm.js maps DECRST of any group member back to the group default, so
a trailing reset would undo the set. Without this, a repainting TUI's
ESC[2J reliably survives raw.py's _trim while the mouse DECSETs it
emitted at startup do not, and every click in lazygit/btop dies at
the first browser reload. The browser→broker paste frame type is a
legacy alias for input (#138), kept only for tabs served before the UI
switched to xterm's paste(). Windows caveat: ConPTY never forwards an
app's ?2004h request to the terminal side (verified live on Server
2022), so for a detected foreground Claude Code — which parses
ESC[200~ regardless — the UI hand-brackets pastes when xterm's own
bracketed-paste mode is off (pasteTextToTerm in the window lifecycle
fragment).
Known limits: no scrollback replay, no alt-screen modeling in snapshots.
Mouse input is forwarded (xterm.js encodes reports onto onData like
any other key), but the sniffer inherits altscreen.py's heuristic
limits — 8-bit CSI (0x9b) is not matched, and 1005/1015 encodings
are untracked because the vendored xterm.js logs both as unsupported.
An outside client (first user: Notifier) can drive one terminal — its
input and its size — without taking the broker's lease, so the desktop keeps
every other terminal. It authenticates with the same browser token as /ws
(no new token class); GET /info carries "terminal_control": 1 on a build
that enforces it. A client feature-detects on that integer.
Every surface carries one view: {"state": "free"|"controlled", "label": <str|null>, "since": <epoch ms|null>, "gen": <int>} (label/since are
null when free). Within one broker run gen is strictly increasing per
terminal id — across a same-id producer reconnect too — so clients may order
views by it and drop any older than the last one they applied. Across a broker
restart it is seeded from the wall clock in milliseconds: that normally keeps
it increasing, but it is not guaranteed if the clock steps back, so a client
re-baselines (forgets its last gen) when the broker restarts.
-
Claim / release, on the controller's own
/ws(so the grant can never outlive the socket): attach as usual (/ws?session=<id>&clientId=<own id>, e.g.ext-<uuid>, never a browser's lease id), then send{"type": "control", "op": "claim", "label": "<str>"}or{"type": "control", "op": "release"}. A claim while another socket holds the terminal takes over. A claim from the holder relabels it at a newgen. The terminal is also released when the controller's socket closes, the terminal exits, or its producer drops or reconnects. A refused op answers{"type": "error", "reason": "bad_label"|"not_controller"|"bad_op"|"unknown_session", "session_id": <id>}and leaves the socket open. -
Label: 1–64 Unicode code points (a JS
lengthcan read up to twice that), shown to the owner verbatim (never normalized). It needs at least one visible character — a letter, number, punctuation or symbol other than the fillers U+115F, U+1160, U+3164, U+FFA0, U+2800, U+17B4, U+17B5 — so a label of only spaces, combining marks, joiners or variation selectors is refused. Refused anywhere: any control, surrogate, unassigned, line/paragraph-separator or format character, except ZWNJ/ZWJ (U+200C/U+200D) — so every bidi control (U+061C, U+200E–200F, U+202A–202E, U+2066–2069) and invisible ones like U+200B/U+FEFF are out. Categories come from the broker's Python Unicode database, so a code point newer than it counts as unassigned. -
The gate: while a controller holds a terminal, only that socket's input
and resize reach the producer. Everyone else's, the lease holder's included,
is dropped, exactly like a non-active socket's. With no controller the lease
rule applies unchanged. A socket that lost the terminal (taken back, or
another claim) watches, and its input is dropped even if its clientId holds
the lease, until it claims again. A controller that dials with a browser's
lease id is one of that browser's sockets: a
become_activeelsewhere closes it with 4409 like the rest, which releases. -
What reaches the producer while controlled: the controller's
input, binary input andresize; legacypasteis gated likeinput, and mouse reports rideinput. Themouseframe type stays a no-op. The snapshot request on every attach, MCP/mcp/input, and the/session/*and/mcp/*management RPCs (read, reset, flush, kill, pace) are not gated: MCP agents are not viewers (they can seecontrolledon/mcp/terminals). -
Size: only the controller resizes; the producer's
resizedecho goes to every viewer as always. Nothing is remembered or restored on release — the next driver's firstresizedecides.
Telling everyone (each change is published to the terminal's /ws
subscribers in gen order, each send bounded at 0.5 s, and every socket ends on
the live view; the /control pushes go out after, so two of them may arrive out
of order — order them by gen). A /ws or /control socket that cannot take a
frame within that bound is closed with 1012, so its page reconnects and re-reads
the state; a controller dropped that way loses control at once:
-
/ws, to every subscriber of that terminal:{"type": "control", ...view}on every change, and once on attach, right afterresizedand before the snapshot. The controller that lost the terminal first gets{"type": "control", "state": "revoked", "by": "browser"|"claim", "gen": <new gen>}. -
/control, to every connected browser:{"type": "terminal_control", "id": <id>, ...view}(a controlled desktop window has closed its/ws, so this is how it hears of a release it did not cause). A terminal that exits while controlled still gets itsfreeview on both surfaces, afterexitand for an id that is already gone, so a page can clear its state. -
GET /sessionsrows:"controller": {"label", "since", "gen"} | null, so a page that boots or rebuilds mid-control re-enters the state.
POST /session/control (browser token) — body {"id": <int>, "op": "release", "gen": <int>, "clientId": "<lease id>"} takes the terminal back
from its controller. The released controller gets revoked (by: "browser")
and keeps its socket as a watcher. Answers, in the order they are checked:
401 auth_required; 400 bad_json / bad_id; 404 unknown_session (also for
a terminal that is exiting); 400 bad_op (op is not "release"); 400 bad_gen (not an integer ≥ 0; a boolean counts as bad); 409 {"ok": false, "error": "not_active"} when another browser holds the lease (clientId,
trimmed, is not the holder) — the same rule as PUT /state, so with no lease
holder at all the browser token alone passes; 409 {"ok": false, "error": "stale_gen", "id", ...live view} when the terminal is free or held at
another gen (a double click or a crossed claim never releases a newer
controller); 200 {"ok": true, "id", ...the new free view}.
The desktop's side (#239). A desktop window whose terminal is controlled
holds no /ws: it closes its socket (handlers nulled), and
attachWebSocket refuses to dial while win.controlled is set, so it receives
nothing and sends nothing. isResizable refuses it too, so no tiling, drag or
browser resize sends a resize, and nothing is queued for later. The page keeps
one record per terminal (<hostId>:<id>, runtime only) fed by all four
surfaces:
- a
/wsframe, a/controlpush or aPOSTanswer is applied only when itsgenis newer than the last one applied; - a
/sessionsrow is applied when that poll was sent after the record last changed, whatever itsgen, which heals a missed push and a broker restart; - a new
/controlsocket to a host forgets that host's gens.
On attach, the resized that comes before the control frame is held until
that frame arrives; a controlled view drops it, so a window never snaps to
the controller's grid. Leaving the state clears the record first and then
reattaches, so the attach's forced initial resize sends this window's size. A
409 not_active from Take back shows the Become active prompt (home broker) or
masks that broker (remote), as a lost lease does.
WS /control carries the single-active-browser lease for one browser profile
(?clientId=<lease id>). Frames the page sends: {"type": "become_active"},
{"type": "ping", "n": <int>} and desktop_result (the answers to a relayed desktop op). Frames it gets:
-
{"type": "status", "active": <bool>, "activeClientId": <str|null>, "gen": <int>, "bootId": "<str>"}— on connect, afterbecome_active, on release, and wherever a status went out before.genis the broker's lease generation: it bumps on every holder change and restarts with the broker, so a page keys "a new holding" on the pair (bootId,gen) —bootIdnames the broker run. A broker that predates #248 sends neither field. -
{"type": "pong", "n": <int|null>, "active", "activeClientId", "gen", "bootId"}— the answer to a ping, on the same socket.nechoes the ping's nonce (nullif the ping carried no integern); the rest is the live lease, built exactly like a status, so a page whose status went missing re-learns it from any ping, and the page runs it through the same path as a status frame. -
A repeat
become_activefrom the current holder is idempotent. It bumps no generation, closes no socket (no 4409) and tells nobody else: only the sending socket gets the status again. Abecome_activefrom anyone else flips the lease, bumpsgen, closes the previous holder's terminal sockets with 4409, and sends every/controlsocket its status. - Every status or pong send is bounded at 0.5 s (
CONTROL_SEND_TIMEOUT); a socket that cannot take one is closed with 1012 and its page reconnects, so one stalled browser never delays the rest. Releasing the lease closes nothing with 4409.
Page-side liveness. The page pings every 25 s with an increasing n. Only a
pong whose n matches an outstanding ping clears the 10 s pong deadline, and
only a socket whose first status carried gen and bootId gets a deadline at
all, so an old broker is never declared dead. On a missed deadline the page
dials a replacement /control socket and keeps the old one working until the
replacement's first status arrives (make-before-break). A 5 s connect/status
watchdog abandons a socket that has not delivered its first status that soon,
and restarts the 5 s once the socket opens. The home broker's channel down for
10 s shows the "lost contact with this broker — retrying…" notice.
Terminal /ws: not_active. When a browser that does not hold the lease
sends input, a paste, a binary frame or a resize on a terminal /ws, the broker
drops it (as before) and answers {"type": "error", "reason": "not_active", "session": <id>}. It is advisory: sent at most once per socket per lease
generation, and never for a socket refused because of a terminal controller (see
Terminal control) or a revoked one. The page writes nothing to the terminal for
it; it asks the lease channel for the live state (a ping), which settles whether
this browser really lost the lease. PUT /state answers a non-holder 409 {"error": "not_active"} as before.
The broker exposes an opt-in HTTP API (the /mcp/* surface) that an MCP
server wraps as MCP tools so an AI agent can list, observe, drive, and launch
terminals. A ready-to-run server ships in webterm/mcptool/
(stdio transport; pip install -e ".[mcp]"). The token-gated endpoints make
up the contract:
| Method | Path | Purpose |
|---|---|---|
| GET | /mcp/info |
feature flags (allow_launch, default_mode, "admin": <bool> #245, "window_edit": true #243, "allow_desktop": <bool> #244) |
| GET | /mcp/terminals |
list MCP-visible terminals |
| POST | /mcp/read |
render a terminal's screen as plain text |
| POST | /mcp/input |
type into a terminal (readwrite only) |
| POST | /mcp/reset |
clear a terminal's screen-render buffer (readwrite only) |
| POST | /mcp/flush |
discard a terminal's unread queued input (readwrite only) |
| POST | /mcp/pace |
set a terminal's default send_keys pacing (readwrite only) |
| GET | /mcp/profiles |
launchable profile names |
| POST | /mcp/launch |
spawn a new terminal from a profile (every launch mints an ownership handle, #243) |
| POST | /mcp/window |
set a window's scope/mode with its launch handle, or any window with the admin credential #245 (#243) |
| POST | /mcp/knobs |
admin-only: set broker-wide knobs (default_mode/allow_launch/allow_desktop) #245 |
| GET | /mcp/desktop |
read the lease-holding browser's desktop snapshot (#244) |
| POST | /mcp/desktop |
relay one desktop op to the lease-holding browser (#244) |
The interface is disabled by default — nothing under /mcp/* answers until
an admin both enables it and sets a token (below). The broker serves the desktop
UI and this API, not this document, so editing these docs needs no restart.
MCP needs both the master enabled flag and a token. With either
missing every /mcp/* request is 403 {"error":"mcp_disabled"}.
Get a token any of three ways (precedence env > sidecar > config seed):
-
Control Panel → MCP access → Generate — mints a
token_urlsafe(32)secret and persists it to the sidecar (below). The normal path. - config
mcp_token— a seed value inbroker_config.json. - env
WEB_TERMINAL_MCP_TOKEN— pins the token over both of the above, is never written to disk, and disables UI token edits (the Control Panel showstoken_env_pinned: true).
Pass it on every /mcp/* request as an Authorization: Bearer <token> header
or a ?token=<token> / ?auth=<token> query parameter (compared in constant
time). A missing/invalid token while the feature is enabled is 401
{"error":"auth_required"}.
This MCP token is a separate secret from the browser auth_token and gates
only the /mcp/* data plane. Like every other surface it has no
loopback exemption (MCP is opt-in, so even a local caller needs the token).
CORS preflights exist for
browser callers; a server-side MCP client makes ordinary requests and is not
subject to CORS.
Each terminal has an effective access mode — its per-window override if set,
otherwise the broker-wide default_mode:
| Mode | Effect |
|---|---|
off |
hidden from /mcp/terminals; /mcp/read + /mcp/input → 404 unknown_or_off (the same answer as a window outside the caller's declared scope) |
read |
visible + /mcp/read; /mcp/input → 403 read_only
|
readwrite |
read and /mcp/input
|
-
default_mode(global, defaultoff) — applies to every window without an override; change it live in Control Panel → MCP access orPOST /mcp/config. -
per-window override — set from the window title-bar MCP access menu or
POST /session/mcp, where"mode": nullclears it so the window inheritsdefault_modeagain. Durable: it is stored with the window's scope inwebterm_mcp_windows.json(see the admin surface below) and re-applied whenever the same producer registers again, across an agent reconnect or a broker restart: same window id, same host, same nonzero process id. An agent relaunched under the same window id is a new process, so it starts back atdefault_mode, and so does a reconnecting producer that reports process id 0. -
allow_launch(global, defaultfalse) — independent flag gating/mcp/launchonly.
A client may declare a scope on any /mcp/* request with the header
X-Browserland-Scope: <name> (#230). The name must fullmatch
[A-Za-z0-9][A-Za-z0-9._-]{0,63}: no : (window ids are host:int) and no
whitespace. A missing header or an empty value means unscoped. A value
outside the grammar, or the header sent more than once, is 400 bad_scope
on every token route, checked after mcp_disabled and the token, so a caller
without the token cannot probe names.
- Unscoped sees every window its mode allows, tagged or not: the legacy/admin view.
-
Scoped
Ssees only windows taggedS./mcp/terminalsomits the rest, and every id-taking route answers an out-of-scope window with the same 404unknown_or_offbytes as a missing one, so existence does not leak. An untagged window is invisible to every scoped caller. -
/mcp/terminalsrows carryscope(the window's tag,nullwhen untagged) and/mcp/infoechoes the caller's declaredscope./mcp/profilesignores the scope. - CORS preflights allow the header unconditionally, and every
/mcp/*response lists it inVary. - A window's tag is set by a scoped
/mcp/launch(below) or by the browser-realmPOST /session/mcp(admin surface), and stored with its mode override inwebterm_mcp_windows.json, so both survive a broker restart. -
GET /info(browser token) carries"mcp_scopes": trueon every broker that implements all of this: the partition,/session/mcp'sscope, and a durable scope and raw mode override. A client feature-detects on it; a broker without the key predates all three. The desktop shows its scope controls only for a broker that says so, and there it stops re-asserting its own synced copy of each window's mode: the broker's stored override is the one authority. - A scope is a convention, not a credential: every client holds the same MCP token and may declare any scope, or none.
The shipped MCP server (webterm.mcptool) fails closed: before its first call to
a scoped host it reads /mcp/info, and it refuses every call to that host with
scope_unsupported when the scope echo is absent (an older broker) or differs
(a proxy dropped or rewrote the header).
One designated agent can manage the whole MCP surface on the owner's behalf.
Admin is its own secret — mcp_admin_token, minted in Control Panel → MCP
access (generate = mint/rotate, clear = remove), pinnable with env
WEB_TERMINAL_MCP_ADMIN_TOKEN (same rules as the token pin: env wins, the
value never reaches disk, UI edits are disabled) — and it is unset by
default, so admin is off out of the box. One shared admin token serves every
admin agent; it is separate from both the MCP token and the #191 browser
admin_token (an MCP admin gets no ADMIN_ROUTES).
Wire. The credential travels as the X-Browserland-Mcp-Admin header
in addition to the normal MCP token — never instead of it. A credential in
the URL query string is refused outright (400 admin_token_in_url, both keys
and values scanned in constant time, logged with the route and peer but never
the value), even when the header is also correct, following the #191 rule —
the broker keeps its own access log off, but a reverse proxy or tunnel in
front of it (nginx, tailscale serve) or the browser's history may record
full URLs, so a token in a query string can leak there: the header is the
only accepted channel. A repeated admin header is refused like a repeated
scope header (403 admin_required — fail closed rather than silently
picking one).
The refusal ladder on every token route is fixed order:
mcp_disabled → 401 auth_required → 400 bad_scope → 403 admin_required
(the header is present but wrong) → the route's own checks. A header sent
while no admin token is configured is ignored (that caller is a plain
non-admin, and /mcp/info answers admin: false); an admin-only operation
called without admin also answers 403 admin_required. CORS: the header name
is advertised unconditionally in /mcp/* preflights (the realm is
runtime-mutable, so a cached conditional answer would go stale for the 86400 s
Max-Age), and every /mcp/* response lists it in Vary.
Reach. An admin lists every window — off windows and foreign-scope
windows included, each row carrying its raw scope and effective mode —
and the out-of-scope unknown_or_off filter is skipped for it (reads and
input still require the window's own mode; mode gates terminal I/O, not
visibility). An admin may set any window's scope/mode (POST /mcp/window
without a launch handle, #243), arrange the desktop when allow_desktop is
on (#244), and set the broker-wide knobs (POST /mcp/knobs, below). An admin
that also declares a scope keeps all of this: the scope is ignored for
visibility and reach, and only tags the admin's own launches.
Never. The MCP token, the admin token and enabled stay browser-only —
/mcp/knobs answers 400 bad_key for them before any write.
allow_desktop (Control Panel → MCP access, POST /mcp/config, or an
admin's POST /mcp/knobs; default off) is the master switch for the whole
desktop relay — window arranging and workspace management, admin included.
GET /mcp/info advertises it as "allow_desktop": true|false. The two routes
below are gated by the full /mcp/* ladder and then by the flag (403
desktop_disabled), and they relay each op to the browser holding the
control lease over its /control socket: one frame per op
({"type":"desktop_rpc","rid":<int>,"op":…,"args":…}), one answer per rid.
-
No lease holder → 409
no_active_browser(fail, never queue); a browser that does not answer within the 10 s end-to-end deadline → 504desktop_timeout; a browser that lost the lease mid-op → 409lost_leasewith nothing half-applied. -
Visibility. Every frame relayed for a NON-admin caller carries
args.visible— the int ids of the caller's visible windows on this broker (effective mode ≠off, in scope), computed at relay time; an admin's frame carriesnull. The browser refusesunknown_windowunless every window the op affects — the named window, plus the whole column formove_column/set_width, plus both windows' columns fortab_into/split— is in that set, and the broker re-checks every named id before relaying, answering the identical 404unknown_or_offbytes.getfor a non-admin keeps only rows whose id is in the visible set (the broker re-filters rows against its own registry as a belt: identity and titles come from the registry, never from the browser). Workspace ops are admin-only at the broker (403 admin_requiredbefore any relay). -
Ops. Window ops:
get,focus,move_column(to=left/rightor an absolute column index — an index move expels a shared window to its own column first, like a drag),set_width(preset=1/3/1/2/2/3/max),tile,float,set_geometry(x,y,w,h, floating only, browser-clamped, answered with the applied box),tab_into(target),split(target,axis=row/column). Workspace ops (workspaces:list/add/rename/remove/switch/send-window) are forwarded to the mod'sctx.commands; the mod being off/absent answers 200{"ok": false, "reason": "inactive"|"absent"}, not an error.
GET /mcp/desktop — op get; answers 200 {"ok": true, …snapshot}.
The snapshot (as the lease-holding browser produces it, after the broker's
registry re-identification) carries viewport, mode, focused_column,
workspaces + active_workspace (null with the mod off), home (whether
that browser's home is this broker), and one row per live window: key,
id (an int for this broker's windows, null for app/foreign windows),
title, tiled, column, row, tabIndex, width_preset (+widthFrac
for a custom width), tabbed/split, minimized, workspace, and
geometry ({x,y,w,h} when floating — per-browser pixel geometry, as that
browser sees it; never stored on the broker) or null when tiled.
Every top-level field is rebuilt and type-checked broker-side — viewport
ints, mode a short string, focused_column/active_workspace int or null,
home a bool, workspaces a bounded list of small typed rows or null — so
a lying or buggy browser cannot smuggle foreign ids or oversized strings
past the relay. Each workspace row is reduced to {index, id, name} with an
unnamed workspace appearing as name: null (only a present, non-string or
oversized name drops the row).
POST /mcp/desktop — body {"op": …, "args": …} with the op allowlist
above (else 400 bad_op); op-specific arg errors answer 400
bad_args. The browser's own error codes map as:
browser error
|
HTTP | body |
|---|---|---|
unknown_window |
404 |
unknown_or_off — byte-identical to the chokepoint's 404 |
bad_args / bad_op
|
400 |
bad_args / bad_op
|
not_home |
409 | workspace op arrived on a non-home broker's relay |
lost_lease |
409 | the browser lost the lease mid-op |
needs_confirm |
409 |
{"error":"needs_confirm","count":<live windows>} — pass force: true
|
last_workspace |
409 | the last workspace cannot be removed |
absent / inactive
|
200 |
{"ok": false, "reason": …} — the workspaces mod is off/absent |
error (op threw) |
502 | desktop_op_failed |
force: true on workspaces:remove moves the windows to the adjacent
workspace; no dialog is ever shown in the browser for an MCP op.
All require a valid MCP token; read/input additionally require the target's
effective mode to permit them.
| Method · Path | Requires | Purpose |
|---|---|---|
GET /mcp/info |
token | feature flags |
GET /mcp/terminals |
token | visible terminals |
POST /mcp/read |
mode ≥ read
|
screen as text |
POST /mcp/input |
mode readwrite
|
send keystrokes |
POST /mcp/reset |
mode readwrite
|
clear the screen-render buffer |
POST /mcp/flush |
mode readwrite
|
discard unread queued input |
POST /mcp/pace |
mode readwrite
|
set the default send_keys pacing |
GET /mcp/profiles |
token | profile names |
POST /mcp/launch |
allow_launch |
spawn a terminal |
POST /mcp/window |
handle or admin | set a window's scope/mode (#243) |
POST /mcp/knobs |
admin credential | broker-wide knobs (#245) |
GET /mcp/desktop |
allow_desktop |
desktop snapshot (#244) |
POST /mcp/desktop |
allow_desktop |
one desktop op (#244) |
GET /mcp/info →
{"ok":true,"allow_launch":false,"default_mode":"off","version":"0.8.0+ba4b62e", "scope":null,"admin":false}.
version is this broker's build id (webterm.build_version() — package version +
git short hash, or the bare package version off a checkout) for stale-deploy
detection (#22). scope is the caller's own declared scope echoed back: null
when it declared none or a proxy stripped the header, and absent from a broker
that predates scopes. A client that declared a scope checks it here to fail
closed (#230). admin (#245) is true only when this call carries a matching
X-Browserland-Mcp-Admin credential — absent from a pre-#245 broker, which
mcptool reads as "not admin" and fails closed on. window_edit (#243) and
allow_desktop (#244) advertise POST /mcp/window and the desktop relay the
same way; a flag absent from an older broker reads as false.
GET /mcp/terminals → an array; windows whose effective mode is off are
omitted, and so are windows outside the caller's declared scope. agent is the
detected foreground-agent name ("" when none), kind the producer kind
("agent" vs a non-agent "terminal"), mode the effective access mode,
scope the window's scope tag (null when untagged). version is the
producer's reported build id ("" for a pre-#22 agent / a non-agent producer);
for agent producers a stale boolean flags a
build differing from this broker's (a deploy predating a fix — reliable when
builds carry a git hash). app_cursor is the cached DECCKM (application-cursor
mode) the MCP send_keys reads to pick CSI vs SS3 arrows (#23); pace_ms is the
window's default send_keys inter-key pacing (#133, 0 = single-burst, set via
/mcp/pace) the MCP server reads so a no-delay_ms send auto-paces. pyte (#134)
is whether the agent has pyte installed: false means its read_screen uses the
dependency-free textgrid fallback — no attr_runs (#128) and no keyframe repair
(#130), so a sparse alt-screen frame after ring eviction comes back flagged
partial only. It defaults true for a pre-#134 agent that omits the field.
controlled (#238) is whether an outside client is driving the terminal right
now (see Terminal control); MCP input is not gated by it:
[{"id":4503603655475937,"title":"bash","host":"JC-SERVER","cwd":"/home/me",
"agent":"","kind":"agent","cols":80,"rows":24,"mode":"read","scope":null,
"version":"0.8.0+ba4b62e","stale":false,"app_cursor":false,"pace_ms":0,
"controlled":false,"pyte":true}]POST /mcp/read — body {"id": <int>} plus optional fields:
view: "scrollback" + lines reads scrollback history instead of the live
screen (lines is hard-capped at 1000, #21; the reply echoes view and
history_lines); since (a prior content_hash) asks for a delta reply —
the response always carries a delta boolean, with changed_rows present
only for a real delta (#52); attrs: true opts into an attr_runs styled-run
map (fg/bg/reverse) so a color-only change is observable (#128).
{"ok":true,"id":4503603655475937,"cols":80,"rows":24,"text":"<screen lines>\n...","content_hash":"…","stable_hash":"…","idle_ms":0}content_hash is a stable 128-bit digest of the rendered text (#26).
stable_hash (#135) is the same digest with the HARDWARE-cursor cell masked to a
sentinel, so a cursor BLINK in place (the cell toggling between the block glyph
and the character under it) leaves it unchanged while a cursor MOVE — which
exposes a different underlying cell — still changes it. It is always present
(empty string for a degraded read or an older agent) and equals content_hash
when there is no cursor.
idle_ms is a best-effort count of ms since the terminal last emitted PTY output
(a current agent always reports it — 0 means output landed just now; an older
agent omits it, so it reads as unknown rather than a misleading 0). It is
unreliable for a perpetually-animating app that paints every frame (its idle_ms
never grows), so pacing/flush and a semantic content wait are the real settle
signals there, not idle_ms.
The read can also BLOCK for one bounded round-trip instead of returning
immediately, on any ONE of four mutually-exclusive wait signals (combining two →
400 conflicting_wait), all capped by timeout_ms (≤ 15000):
wait_for_change (a prior content_hash — wake when the screen differs, #26),
wait_for_text / wait_for_regex (+ wait_absent — wake when the grid contains
or no longer contains a match, #51), and wait_for_idle (a settle window in ms —
wake once stable_hash has held steady for that many ms, i.e. output went quiet,
#135). The predicate and idle waits set matched (true when satisfied, false on
timeout); the RPC timeout is stretched by timeout_ms so the agent's hold
outlives it. wait_for_idle settles only a CALMER TUI — a fully-animating app
(Dwarf Fortress animates creatures/water/the *PAUSED* marquee off the cursor
every frame) never reaches output-idle, so there use pacing/flush plus a semantic
wait_for_text check, not idle.
The agent renders the screen off its event loop. With pyte it returns the full
grid; without pyte it falls back to a dependency-free in-house emulator
(agent/snapshot/textgrid.py) that still produces a bounded rows×cols
grid — so a full-screen TUI reads as a clean grid (box-drawing/braille intact),
not an unbounded raw-ANSI dump (#15). Both paths are real grid renders, so
"degraded": true is now reserved for the rare last-ditch raw decode (it
no longer appears for ordinary TUIs). The textgrid fallback has no keyframe
repair (that is pyte-only, #130), so a sparse alt-screen frame after ring
eviction comes back flagged "partial": true (#134) — the grid is a real
render, just possibly incomplete; the per-terminal pyte flag on
/mcp/terminals tells a caller up front which path an agent is on. Only
agent producers answer; a non-agent terminal producer has no handler, so the
request times out → 502 {"error":"no_producer_rpc"}.
POST /mcp/input — body {"id": <int>, "data": "<str>"} → {"ok":true}.
Requires effective mode readwrite (else 403 read_only); data must be a
string (else 400 bad_data) and ≤ 256 KiB UTF-8 (else 413
too_large). Forwarded verbatim straight to the PTY and deliberately
bypasses the single-active-browser lease — MCP is its own authorized channel.
It bypasses a terminal's external controller (#238) the same way.
The high-level MCP send_input tool maps newlines in data to a carriage
return before calling this endpoint, so a command submits on PowerShell/PSReadLine
(which treats a bare \n as a soft continuation) and on a Unix shell alike (#13);
the endpoint itself is byte-exact, so drive it directly for a literal LF or
raw-mode bytes.
POST /mcp/reset — body {"id": <int>} → {"ok":true,"id":<int>}. Requires
effective mode readwrite (else 403 read_only). A correlated producer
round-trip (like /mcp/read): the agent clears its PTY-output ring so the next
read_screen renders from a clean slate, then acks. Only agent producers
answer; a non-agent producer times out → 502 no_producer_rpc (and a rare
agent-side failure → 502 reset_failed). It touches Browserland's render
buffer only — it sends nothing to the running app.
POST /mcp/flush — body {"id": <int>} → {"ok":true,"id":<int>}. Requires
effective mode readwrite (else 403 read_only). The input-side mirror
of /mcp/reset: where reset clears the OUTPUT ring, this discards keystrokes
queued toward the app but not yet consumed (a runaway send_keys backlog a
frame-polling TUI hasn't drained), so the next read_screen reflects the settled
state. Same correlated round-trip — only agent producers answer, so a
non-agent producer times out → 502 no_producer_rpc (a rare agent-side
failure → 502 flush_failed). On a Windows/ConPTY agent it is a best-effort
no-op (that backend exposes no input-queue flush primitive) and still acks ok.
POST /mcp/pace — body {"id": <int>, "pace_ms": <int>} →
{"ok":true,"id":<int>,"pace_ms":<clamped int>}. Requires effective mode
readwrite (else 403 read_only). Sets the window's default send_keys
inter-key pacing so a subsequent MCP send_keys that passes no delay_ms
auto-paces (one key per POST) — for a frame-polling raw-input TUI (Dwarf Fortress)
that drops a burst read faster than it renders. pace_ms must be an integer (else
400 bad_pace) and is clamped to [0, 1000] (0 disables → single-burst;
an over-cap value pins to 1000). Unlike /mcp/reset//mcp/flush this is
broker-local with no producer round-trip — it just stamps the window's
in-memory pace_ms, which /mcp/terminals surfaces for the MCP server's
client-side pacer. The value is ephemeral per-connection: it resets whenever
the window registers again (agent reconnect or relaunch). Unlike a per-window
mode override, it never carries over a reconnect.
GET /mcp/profiles → {"default":"cmd","profiles":["cmd","powershell"]}
(the broker's configured agent.profiles; bash/sh on Linux). Profiles
are global: a declared scope never changes this list, and a scoped caller may
launch any of them.
POST /mcp/launch — requires allow_launch (else 403 launch_disabled).
Body reuses the /launch shape plus an MCP-only mode: {"profile": <str>, "cols": 80, "rows": 24, "title": <str>, "cwd": <str>, "mode": "off"|"read"|"readwrite"}, all optional (dims default 80×24, profile
defaults to the broker default; cwd must be an existing dir; an invalid
mode is 400 bad_mode, scoped or not, and null counts as absent).
Response is the launcher's:
{"ok":true,"id":4503603655475937,"registered":true,"agent_pid":12345}200 when the agent registered within 10 s, 202 when it spawned but had
not said hello yet ("registered":false).
Every MCP launch, scoped or not, takes the same path (#243): the window's
row in webterm_mcp_windows.json is written before the agent is spawned, with
a null pid and host, and the agent's first hello claims it — even a hello
that reaches a restarted broker after a 202. The window comes up in the body's
mode, or in readwrite when there is none (not default_mode,
scoped or unscoped alike: a launched worker is meant to be driven by its
launcher, and allow_launch is already its own opt-in). The broker also mints
a launch handle — secrets.token_urlsafe(32) — and stores only its SHA-256
hex digest as the row's owner; the plaintext handle is returned in the
response ("handle": "…", alongside "scope" and "mode"; "scope" is
null for an unscoped launch) and nowhere else. An unscoped launch's row
survives on its owner (and mode) even with no scope. If the launch fails
after the row was written, the row is removed again — unless the agent's
hello already claimed it. A launch whose new window id already has a stored
row retries once on a fresh id; the collided row is deleted only when it
is a pre-spawn orphan (no pid and no host) or older than the 7-day prune age
— never a row a reconnecting producer could still claim, whose off/scope
policy stays untouched (the retry runs whether or not the row was deleted).
Only a row write that fails, or a retry whose fresh id collides again, is
500 prespawn_failed, and nothing is spawned. The browser's
/launch is unchanged: it never reads mode and writes no row.
POST /mcp/window — body {"id": <int>, "handle"?: <str>, "scope"?: <str>|null, "mode"?: "off"|"read"|"readwrite"|null} (#243). Sets the scope
and/or MCP mode of one window; an absent key leaves its field, an explicit
null clears it (exactly /session/mcp's body rules). Two paths, tried in
order:
-
handle (preferred, admin included): the row must carry an
owner, the caller's handle must hash to it (constant-time compare), and a live entry for the id must be the row's own producer. The handle bypasses the off/out-of-scope filter — an owner can set its window tooff, or to a scope it does not hold, and undo it. A matching-handle write keeps the owner. - no handle: requires the admin credential; the write targets any window with a live entry or a stored row, and clears the old owner (a stale agent handle cannot undo an admin decision) while stamping the window as admin-driven (the taskbar badge).
Every handle-path failure — a wrong or missing handle, an unknown id, an
unowned row, a foreign producer — answers the identical 404
unknown_or_off bytes as every other id-taking route, so the route cannot
be used to probe which ids exist. Validation (bad_json/bad_id, bad_mode,
bad_scope — 400) runs before any write, and the authorization is re-checked
inside the store's single locked write, so an admin's owner-clear landing
between validation and commit turns a stale handle into the same 404 rather
than a write. The change persists across a broker restart and is re-applied on
the same producer's reconnect; a /session/mcp edit clears the row's owner,
after which the old handle gets the 404; a pre-spawn row (202 window before
its first hello) is editable by its owner. GET /mcp/info answers
"window_edit": true on a broker that has this route.
| Status | error |
When |
|---|---|---|
| 403 | mcp_disabled |
feature disabled or no token configured |
| 401 | auth_required |
missing/invalid MCP token |
| 400 | bad_scope |
X-Browserland-Scope is not a valid scope name, or is sent more than once (so a proxy that adds its own copy makes every call a 400); every token route, checked after mcp_disabled and the token. An empty value is not refused: it means unscoped, which sees every window its mode allows |
| 400 | bad_json |
body is not a JSON object |
| 400 | bad_id |
id missing or not an integer |
| 404 | unknown_or_off |
no such window, or its effective mode is off, or it is outside the caller's declared scope; on POST /mcp/window (#243) every handle-path failure answers these same bytes, so ids cannot be probed |
| 400 | bad_data |
/mcp/input data is not a string |
| 403 | read_only |
/mcp/input on a window not in readwrite
|
| 413 | too_large |
/mcp/input payload > 256 KiB |
| 400 | bad_pace |
/mcp/pace pace_ms missing or not an integer |
| 502 | no_producer_rpc |
/mcp/read · /mcp/reset · /mcp/flush producer did not answer (non-agent / timeout) |
| 502 | reset_failed |
/mcp/reset agent could not clear its render buffer |
| 502 | flush_failed |
/mcp/flush agent could not flush its pending input |
| 403 | launch_disabled |
/mcp/launch with allow_launch:false
|
| 400 | unknown_profile |
/mcp/launch profile not in config |
| 400 |
bad_dims / bad_cwd / cwd_not_dir
|
/mcp/launch bad cols/rows/cwd
|
| 429 | too_many_pending_launches |
/mcp/launch backpressure |
| 400 | bad_mode |
/mcp/launch mode is not off/read/readwrite (or null) |
| 500 |
spawn_failed / agent_exited_early
|
/mcp/launch agent failed to start |
| 500 | prespawn_failed |
/mcp/launch: the new window's row could not be written, or the one retry's fresh id also had a stored row; nothing was spawned |
| 400 | admin_token_in_url |
an MCP admin credential was sent in the URL query string (#245) — the header is the only accepted channel, and the refusal holds even when the header is also correct |
| 403 | admin_required |
the X-Browserland-Mcp-Admin header is present but wrong, or an admin-only operation was called without admin (#245) |
| 400 | bad_key |
POST /mcp/knobs carries a key outside its three knobs — token, admin_token and enabled are browser-only (#245) |
| 400 | bad_value |
POST /mcp/knobs boolean knob is not a real JSON boolean ("false" is refused, not coerced) |
| 403 | desktop_disabled |
the desktop relay's allow_desktop switch is off (#244) |
| 409 | no_active_browser |
/mcp/desktop with no browser holding the control lease (ops are never queued) |
| 504 | desktop_timeout |
the lease-holding browser did not answer the desktop op in time |
| 409 | not_home |
a workspaces:* op arrived on a relay whose lease holder's home is another broker |
| 409 | lost_lease |
the browser lost the control lease mid-op; nothing was half-applied |
| 409 | needs_confirm |
workspaces:remove of a non-empty workspace without force: true — the body carries the live window count
|
| 409 | last_workspace |
the last workspace cannot be removed |
| 502 | desktop_op_failed |
the browser's desktop op raised |
| 400 |
bad_op / bad_args
|
/mcp/desktop op outside the allowlist / op arguments invalid |
These configure MCP and are not part of the MCP token's surface. They use
the browser auth_token (the same mandatory-token gate as /state and
/file/*): always required, on every interface, as Authorization: Bearer or
?token=.
GET /mcp/config →
{"ok":true,"enabled":false,"token":"","admin_token":"","admin_token_env_pinned":false, "default_mode":"off","allow_launch":false,"allow_desktop":false, "token_env_pinned":false,"known_scopes":[],"python":"/usr/bin/python3", "pythonpath":"/opt/browserland","local_url":"http://127.0.0.1:4445"} (token
and admin_token are the live secrets, "" when unset). admin_token (#245)
is the MCP admin credential, shown to the browser-token holder like token
(the browser is the root of trust); admin_token_env_pinned mirrors
token_env_pinned for it — WEB_TERMINAL_MCP_ADMIN_TOKEN pins the admin
token (env wins over the sidecar, the value never reaches disk, and the
Control Panel's admin controls are disabled). allow_desktop (#244) is the
desktop relay's master switch — a browser checkbox and an admin knob.
known_scopes lists the scopes on live
windows (any mode) and on stored per-window rows, sorted; a name a caller only
declared on the header never appears. python is the interpreter running this
broker (sys.executable), pythonpath the directory holding the webterm
package it runs, and local_url a loopback URL on the port this request
arrived on (the configured port when there is no socket to read); the Control
Panel's Copy .mcp.json builds a client file from them (#235). They are
absolute server paths, shown only to a holder of the browser token.
POST /mcp/config — partial update of any of enabled, default_mode
(off/read/readwrite), allow_launch, allow_desktop (#244), token,
generate:true (mint a
fresh token_urlsafe(32)), admin_token (the #245 credential: null or ""
clears it) or admin_generate:true (mint/rotate — a server-minted value only,
never a client-chosen secret). Validated before any write; returns the GET
shape. While the env pins the token, token/generate edits are ignored
(the live token stays the env value), and the same rule holds for
admin_token/admin_generate under WEB_TERMINAL_MCP_ADMIN_TOKEN. Errors:
bad_json (400), bad_mode (400),
bad_token (400, non-string token/admin_token).
POST /mcp/knobs (#245, admin credential required) — body
{"default_mode"?: "off"|"read"|"readwrite", "allow_launch"?: bool, "allow_desktop"?: bool} →
{"ok":true,"default_mode":…,"allow_launch":…,"allow_desktop":…}.
The admin agent's broker-wide
knobs, validated before any write: an unknown key — in particular token,
admin_token or enabled, which stay browser-only — is 400 bad_key, and
the booleans must be real JSON booleans (a string "false" is truthy junk →
400 bad_value, not coerced: the browser realm's /mcp/config keeps its
historical coercion as pinned wire). A non-admin call is 403
admin_required before any validation. The write shares /mcp/config's
locked sidecar writer, so the two routes never interleave.
POST /session/mcp — body {"id": <int>, "mode": "off"|"read"|"readwrite"|null, "scope": <str>|null}, both keys optional →
{"ok":true,"id":<int>,"mode":<str|null>,"scope":<str|null>}. Sets the
window's per-window mode override, its scope, or both; a key left out leaves
that field as it was. "mode": null clears the override (the window inherits
default_mode); "scope": null or "" untags the window; a scope name matches
[A-Za-z0-9][A-Za-z0-9._-]{0,63}. The response carries the stored values: mode
is the RAW override (null while inheriting), never the effective mode. Every
change is written to webterm_mcp_windows.json before it takes effect, so it
survives a broker restart (see Access modes), and an identical repeat writes
nothing. A browser-side edit also clears the row's owner (#243) — the human
decision wins over the launching agent's handle, which stops working at once.
Errors, in the order they are checked: bad_json / bad_id (400),
unknown_session (404, no live window with that id; nothing is stored),
bad_mode (400, an invalid mode, or neither mode nor scope given),
bad_scope (400), write_failed (500, the store could not be written; nothing
changed).
Sidecar webterm_mcp.json — the durable MCP config, written atomically next
to the /state store (default <state_path dir>/webterm_mcp.json; override with
config mcp_state_path). Schema:
{"token": "<secret or null>", "admin_token": "<secret or null>",
"default_mode": "off", "allow_launch": false,
"allow_desktop": false, "enabled": true}token is null when the env pins it (the secret stays off disk), and so is
admin_token under its own pin; allow_desktop (#244) is the desktop relay's
master switch, default off. The file self-heals if hand-edited or
truncated. It holds only these broker-wide knobs: per-window modes and scopes
live in webterm_mcp_windows.json, below.
Sidecar webterm_mcp_windows.json — the durable per-window MCP store,
written atomically next to the /state store (default
<state_path dir>/webterm_mcp_windows.json; override with config
mcp_windows_path). One row per window id:
{"windows": {"<window id>": {"scope": "<str or null>", "mode": "<str or null>",
"owner": "<64-hex sha256 or null>",
"admin_set": false,
"pid": 12345, "host": "<str or null>",
"seen": 1790000000}}}mode is the RAW override (null = inherit default_mode), owner (#243)
is the SHA-256 hex digest of a launch handle (never the handle itself), and
admin_set (#245) marks a window an admin credential launched or last
re-tagged (it feeds the taskbar's mcp_admin flag on /sessions). A row
carrying none of scope, mode or owner is deleted. pid (an int or null) and
host name
the producer the row was written for. Window ids are reused (an OS window
handle is recycled), so a row is re-applied only to a hello from the same host
with the same nonzero pid; a null pid or host is a wildcard, claimed by the
first hello with a nonzero pid that matches the rest (an /mcp/launch
writes its row that way, before the agent exists). seen (epoch seconds)
moves whenever a hello re-applies the row or a write changes it, and once a day
while the window stays connected; the hello bumps reach disk through a
coalesced writer, at most once a minute. Rows are never pruned at load, nor
during the first 10 minutes after the broker starts (every window gets that
long to reconnect). After that, each write drops rows whose window is not
connected and that were not seen for 7 days, then, while more than 1000 rows
remain, the oldest rows whose window is not connected (a connected window's
row is never dropped). A missing, unreadable or wrong-shaped file starts the
store empty and a malformed row is dropped, both logged; the next change
rewrites the file.
Precedence. Token: env WEB_TERMINAL_MCP_TOKEN > sidecar token > config
mcp_token. Effective mode: per-window override > global default_mode.
The Control Panel edits the launch-profile allow-list here. Same mandatory
browser-token gate as /mcp/config above — never the MCP token, so the
commands (the RCE-by-design half of profiles-only) only ever travel to an
already-authenticated browser. /profiles and /mcp/profiles stay names
only, so an MCP/AI agent still can't read a command or define a profile.
GET /profiles/config → the full objects for this host:
{"ok":true,"default_profile":"cmd","profiles":{"cmd":{"command":[...],"title":..., "cwd":...}},"os":"windows|posix","source":"config|sidecar","exists":{"cmd":true}}.
exists[name] is shutil.which(command[0]) is not None (a red flag for a
shell that isn't installed).
POST /profiles/config — replace semantics; body
{"profiles":{...},"default_profile":"..."}. Validated in full before any
write (a bad field changes nothing), then written to the sidecar atomically and
the live launcher is swapped — no restart. Returns the GET shape. Errors
(all 400 unless noted): too_large (413, body > 256 KiB), bad_json,
bad_profiles (not a dict), no_profiles (empty — would brick /launch),
too_many_profiles (> 200), bad_name (empty / > 64 chars / control chars /
outside [A-Za-z0-9 ._+-]), bad_profile, bad_command (not a non-empty list
of non-empty control-char-free strings), command_too_long,
command_token_too_long, bad_title/title_too_long, bad_cwd/cwd_too_long,
default_not_member. An empty default_profile resolves to the first profile.
GET /profiles/detect → read-only environment scan seeding the editor:
{"ok":true,"suggestions":[{"name","title","command","exists"}]}. Windows lists
WSL distros (wsl.exe -l -q); POSIX lists installed bash/zsh/fish/sh.
Never errors on a missing tool — the list is just empty. Runs off the event loop.
Sidecar webterm_profiles.json — the durable profile set, written atomically
next to the /state store (default <state_path dir>/webterm_profiles.json;
override with config profiles_state_path). Schema:
{"profiles": {"<name>": {"command": ["..."], "title": null, "cwd": null}},
"default_profile": "<name>"}Seeded from broker_config.json's agent.profiles; once written it owns the
set (agent.profiles becomes seed-only). Self-heals — a missing/corrupt/empty
sidecar falls back to the seed, never bricking startup or /launch. Full recipe
catalog + the security rationale: Launch-Profiles.
The desktop's mod system. Authoring contract, the ctx API and the trust model:
Writing-a-Mod. All of these are serve_ui-gated — a headless
broker registers none of them and reports mods: [] — and, like
/mcp/config, they take the browser token, never the MCP one. They are
deliberately not lease-gated: this is broker configuration, and the point is
being able to administer a broker somebody else is using right now.
A mod is not sandboxed. It runs same-origin with the page's full authority
and can reach /file/*, /session/*, /state and /mcp/* directly; ctx
grants it nothing it lacks. So the trust event is the token-gated install,
not the fetch that follows.
POST /mods/policy — this broker's mod pins, {modId: bool}, applied to
every browser that loads its page (an absent id leaves the choice to that
browser). Stored in the webterm_mod_policy.json sidecar beside the /state
store (override with config mod_policy_path); reported by GET /info as
mod_policy. Applies on the next page load.
POST /mods/install — body
{"manifest": {…}, "files": {"<name>": "<text>"}, "replace": false}, ≤ 2 MiB,
validated entirely in memory before a byte is written. The mod id must match
[a-z0-9][a-z0-9-]{0,63} and start with x- (reserved_id otherwise — the
un-prefixed namespace is reserved for shipped mods). manifest.scripts is a
required non-empty list of .js names; entry and every other unknown key are
rejected, not ignored. Files are text only (.js/.css/.md), UTF-8,
BOM-free, newline-terminated, ≤ ui._MAX_LINES lines; a .css may not
@import or reference an absolute url(http…). Caps: 32 mods, 32 files/mod,
256 KiB/file, 512 KiB/mod. Returns
{"ok":true,"id","gen","replaced","adopts_existing_state":{"mod_store","pin"}, "mod":{…},"applies":"next_page_load"}. Errors (each distinct): too_large
(413), bad_json, bad_mod_id, bad_generation, reserved_id, id_in_use
(409), bad_file_name, reserved_file_name, too_many_files, file_too_large
(413), total_too_large (413), bad_encoding, bad_scripts, bad_styles,
bad_requires, bad_manifest_field, unknown_manifest_key,
css_external_reference, too_many_mods (409), write_failed (500).
POST /mods/uninstall — {"id": "x-notes", "purge": false}. purge:true
also clears this broker's /mod-store/<id> and its pin (lock order
mods_install → mod_policy → modstore, data-first/code-last); it cannot touch
what other browsers hold in localStorage. Not idempotent at the HTTP level:
a retry after a lost response answers 404 not_installed even though the first
attempt succeeded — treat that as possible success.
POST /mods/rescan — re-read mods_dir and sweep litter. An operator
convenience, not a trust boundary (anyone who can write mods_dir can write
the broker's source tree); the scanner refuses symlinks/reparse points, refuses
anything whose realpath leaves mods_dir, refuses a non-x- directory, and
validates every byte under the same rules an install obeys. The destructive
sweep refuses to run in a directory without the .browserland-mods marker.
GET /mods/installed — the operator detail /info leaves out: mods_dir,
per-file sizes and sha256s, installed_at, declared tiers, has_help, the
effective limits, and what was skipped and why.
GET /mods/<modId>/<gen>/<name> — one file of one generation of one
installed mod. Public, and forced rather than chosen: a <script src>
cannot carry an Authorization header, ?token= is structurally banned (#144),
and a fetch+blob: workaround would need blob: in script-src. Same
posture as GET /, which already carries every shipped mod's source. Served
from an in-memory allowlist dict keyed "<id>/<gen>/<name>" — a client-supplied
segment can only ever hit a known key, so traversal is unrepresentable rather
than defended against, and no blocking IO reaches the event loop. Only
.js/.css are servable. Cache-Control: public, max-age=31536000, immutable
is honest because <gen> is a content hash. Installed source and styles are
therefore readable by anyone who knows the id, the generation and the file name
— do not put a secret in a mod. help.md is not servable here at all
(content_type returns None for it); its only surface is
/help-corpus.json, which since #173 withholds the installed sections — and so
the installed ids — from a caller with no token.
<gen> is not a second secret. compute_gen is sha256 over the canonical
manifest plus the sorted (name, sha256) pairs — no salt, no broker id, no
install timestamp — so anyone holding the exact bytes of a distributed package
recomputes the gen this broker stored, and a 200 here rather than a 404
confirms it is installed. That is a confirmation oracle over a candidate set
the caller already has, not enumeration: a mod whose bytes were never
published stays unguessable in both segments, and what leaks about a public one
is one bit about code this route serves in full anyway. #173 is therefore
partial by construction — it stops the corpus listing installed ids, it
cannot hide a publicly distributed mod from someone who asks for it by name.
Salting the gen would close it and is deliberately not done: a generation's
directory name must content-address its own bytes (the scanner refuses one that
does not), which is what makes reinstalling identical bytes a no-op, keeps two
brokers' URLs for one package agreeing, and makes immutable honest.
Store mods_dir — runtime-installed mods live in a directory beside the
/state store (default <state dir>/webterm_mods; override with config
mods_dir), deliberately not webterm/broker/mods/, whose drift guard is
bidirectional. Layout <id>/CURRENT (the atomic {"gen": …} commit pointer) +
<id>/<gen>/ holding mod.json, the mod's files and broker-written
.gen.json. gen is a sha256 over the canonical manifest plus the sorted
(name, sha256) pairs; two generations are retained, so a page that started
booting against one cannot be handed a file from the next mid-flight.
Install/uninstall applies on the NEXT PAGE LOAD, never live, and that is
forced: global lexical bindings cannot be removed, so re-executing a mod script
in the same page dies with SyntaxError: Identifier … has already been declared. ?nomods=1 on the desktop URL boots with no mod fetched or
initialized at all — the rescue hatch when an installed mod makes the Control
Panel unreachable.
B=http://127.0.0.1:4445
# Admin (add -H "Authorization: Bearer $AUTH" — a token is always required):
# enable MCP, mint a token, default new windows to read, allow launching.
curl -s -X POST $B/mcp/config -H 'content-type: application/json' \
-d '{"enabled":true,"generate":true,"default_mode":"read","allow_launch":true}'
# -> {"ok":true,"enabled":true,"token":"abc123...","default_mode":"read",...}
TOK='abc123...' # the token from above
curl -s $B/mcp/info -H "Authorization: Bearer $TOK"
curl -s $B/mcp/terminals -H "Authorization: Bearer $TOK"
curl -s $B/mcp/profiles -H "Authorization: Bearer $TOK"
# Read a terminal's screen (use an id from /mcp/terminals):
curl -s -X POST $B/mcp/read -H "Authorization: Bearer $TOK" \
-H 'content-type: application/json' -d '{"id":4503603655475937}'
# Promote that window to readwrite (admin), then type into it:
curl -s -X POST $B/session/mcp -H 'content-type: application/json' \
-d '{"id":4503603655475937,"mode":"readwrite"}'
curl -s -X POST $B/mcp/input -H "Authorization: Bearer $TOK" \
-H 'content-type: application/json' -d '{"id":4503603655475937,"data":"ls\n"}'
# Launch a new terminal from a profile:
curl -s -X POST $B/mcp/launch -H "Authorization: Bearer $TOK" \
-H 'content-type: application/json' -d '{"profile":"bash","cols":100,"rows":30}'A ready-to-run MCP server lives in webterm/mcptool/ — a
thin stdio wrapper that maps each endpoint above to an MCP tool (mcp_info,
list_terminals, list_profiles, read_screen, send_input, send_keys,
set_pace, reset_terminal, flush_input, launch_terminal). It connects to
the broker over HTTP and authenticates with the MCP token.
pip install -e ".[mcp]" # needs Python >=3.10 (the mcp SDK)
claude mcp add browserland --env BROWSERLAND_MCP_TOKEN=… -- python -m webterm.mcptoolSee webterm/mcptool/README.md for config (env/flags), the
tool list, and how access modes / allow_launch still govern behavior.
python -m pytest tests -qThe full suite passes (the platform PTY e2e suites skip on the other
OS): protocol shapes, ring eviction, OSC sniffer split at every byte
index, raw/pyte snapshot rendering, agent↔fake-broker integration
(reconnect, snapshot ordering, title re-hello), real-ConPTY round trip
on Windows, real-POSIX-PTY round trip on Linux (bash
echo/resize/stty size/OSC title/exit code, Ctrl-C via TIOCSCTTY,
huge-paste backpressure), broker e2e as a subprocess (auth gates, CORS on
error paths and preflights, sanic-ext neutralized, relay invariants,
/launch → detached agent on both platforms), the mandatory-token policy
(token bootstrap/mint/adopt, a router-enumerating guard that every non-public
route answers 401 auth_required, and the WS 4401 gates on loopback),
non-loopback auth negatives + CORS positives via the box's LAN IP, plus the
newer surfaces: the MCP tools (read/reset/flush/pace),
the file API, session recording, the status-fetch proxy, the textgrid
fallback renderer, and UI asset assembly.
pyte is optional: pip install pyte. It is required only for
--snapshot-mode pyte (raw starts without it), but installing it also
upgrades MCP read_screen regardless of snapshot mode — attr_runs (#128)
and keyframe repair (#130); without it the dependency-free textgrid
fallback is used and a sparse alt-screen frame after ring eviction comes
back flagged partial (#134). Windows agents need pywinpty>=2.
This broker's relay and registry were adapted from xterm-py
(https://github.com/JohnConnorNPC/xterm-py), a separate
relay/registry/UI codebase, which is not part of or modified by this
project. This broker defaults to port 4445.
Browserland — a web-based terminal desktop. This wiki is the end-user guide; for the wire protocol, auth model, and HTTP/MCP contract see Technical Reference. Released under the MIT License.
Start here
Building layouts
The desktop
Windows & content
Multi-host & AI
For developers