Repository navigation
Upgrading
Breaking changes, what they cost you, and how to recover. Newest first.
Nothing to do, and nothing is lost. This is here because the persisted layout changes shape on first load, and because the feature can now be turned off.
prefs._layout used to group tiled columns under workspaces:[...] with an
activeWs index, and the tiling core owned that model. It is now a single
desktop:
before { mode, activeWs, workspaces:[ {id, name?, focusedCol, columns:[...]} ] }
after { mode, focusedCol, columns:[...],
mods: { workspaces: { version:1, activeId, list:[{id,name?,focusedCol,focusedColId?,focusedColIdAt?}] } } }
Every column lives in columns exactly once. Workspaces are a mod
(mods/workspaces/, enabled by default) that stamps a wsId on each
column and tells the strip which ones to draw.
Nothing, on either path:
-
Upgrading. The first
getLayout()concatenates your existing workspaces' columns intocolumns, in order, and hands the grouping to the mod, which rebuilds your workspaces from it. Names and the workspace you were last on are preserved. The migration is one-way and idempotent, and it is non-destructive — no column is dropped even if the mod never loads — so a browser that migrates first cannot damage a peer that has not yet. - Turning the mod off. Every column from every workspace appears together on one desktop; the pager, the seven workspace shortcuts and the workspace menu items go away. Your grouping is kept, not deleted: turn it back on and the workspaces return exactly as they were. The same is true of pinning it off broker-wide (Control Panel -> Mods on this broker).
Your keyboard bindings for workspace-prev / workspace-next /
workspace-1..5 are stored by action id and are untouched by any of this.
An older build reads the new blob as a layout with no workspaces key, which
its reconcileLayout heals into one workspace holding no columns — your
windows come back as floating windows rather than tiled, and you would rebuild
the layout. Keep a copy of webterm_state.json if you plan to roll back.
This breaks tokenless installs. It cannot not break them — the whole point is that a request which used to be accepted is now refused. Read the table below to find your case.
Browserland used to treat loopback as an auth exemption. Three problems:
-
With no
auth_tokenconfigured — the shipped default —/sessions,/profiles,/wsand/controlwere gated by a check that did nothing when no token existed. On a0.0.0.0or tailnet bind that was an open read of every terminal's title, pid and cwd, an open attach to every PTY, and an open steal of the single-active-browser lease. -
Loopback never meant "same machine." The recommended topology is
tailscale servein front of a127.0.0.1bind — and a proxied request arrives from loopback. So the recommended deployment handed the whole tailnet an exempt path to/launch(shell spawn) and/file/*(host-wide read/write). A page in your own browser reaches loopback too. -
/browserlandwas exempt even when a token WAS configured — the one gate the token never covered. WebSockets are not CORS-gated, so any website you had open could dialws://127.0.0.1:4445/browserland, re-register a live window id (kicking the real agent off) and inject fabricated output into a terminal you trust.
Now: a token is required on every surface, on every interface, always. There is no loopback exemption and no opt-out.
The only unauthenticated responses are GET / (the token is typed into that
page, and auth is query/header-only with no cookies — gating the document would
401 every reload, bookmark and new tab forever), GET /help-corpus.json, and
the OPTIONS preflights, which carry no credentials by design. /mcp/* keeps
its own separate mcp_token realm.
A fresh install still works with one command. With nothing configured the
broker mints its own token into webterm_token.json beside its state store and
prints a ready-to-open ?token=… URL.
| Your install | What breaks | Recovery |
|---|---|---|
| Tokenless, loopback only (the shipped default) | The browser asks for a token on next load. Terminals launched before the restart are stranded. Scripts curling /sessions, /file/* or /launch over loopback now get 401. |
The token is printed at startup and by --print-token. Relaunch the terminals. |
Tokenless behind tailscale serve / a proxy |
Same, plus every remote browser must enter the token once. | Same. |
auth_token already configured |
Almost nothing. Running agents already carry WEB_TERMINAL_TOKEN and reconnect fine; browsers already stored it. Only hand-started local agents and tokenless local scripts break. |
launchers/run-agent.{sh,ps1} now read the sidecar automatically, or set $WEB_TERMINAL_TOKEN. |
MCP clients (webterm.mcptool) |
Nothing. Separate mcp_token, Authorization: Bearer, /mcp/* realm — untouched. |
— |
Headless (serve_ui: false) |
Nothing. GET / still answers 200 {"ui": false}, so health probes keep working. |
— |
python -m webterm.broker --print-tokenPrints the token and the URL to open, without starting a server. It never mints one — asking for the token must not be the thing that creates it.
Resolution order, for the broker and for --print-token alike:
$WEB_TERMINAL_TOKEN-
auth_tokeninbroker_config.json -
webterm_token.jsonbeside the state store - (broker only) mint a new one into that file
If you were running tokenless, the terminals that broker launched were
spawned with WEB_TERMINAL_TOKEN deliberately removed from their environment.
After you restart the broker they cannot re-register.
Their shells keep running. Their windows never come back. There is no server-side rescue: an environment variable cannot be injected into a live process. The broker notices this happening and, after a few refused producer connections, logs what it means and points here.
So, before deploying:
- Finish or accept the loss of whatever is running in those terminals.
- Consider setting an explicit
auth_tokenin your config before the cutover, so you know the value in advance rather than discovering it in the log afterwards. - Then restart the broker and relaunch your terminals once. From then on everything self-heals: terminals launched by the UI get the token from the broker automatically.
-
The startup banner prints the full
?token=…URL only on the run that minted it, and only to an interactive terminal. Under systemd, Docker or CI it prints a pointer to--print-tokeninstead, so a live credential is not baked into aggregated logs. Sanic's access log is now off for the same reason (the token rides in the query string). -
A first start against a directory that already holds broker state prints a
loud
UPGRADE NOTICE— that combination means this install used to run tokenless. -
The token is no longer visible from inside your terminals. The agent
removes
WEB_TERMINAL_TOKENbefore spawning your shell, soecho $WEB_TERMINAL_TOKENis empty. Shell-side automation that needs it should readwebterm_token.jsonor run--print-token. -
An agent refused for a missing token retries every 10 s instead of once a
second, and logs one error naming
$WEB_TERMINAL_TOKEN. It does not give up permanently — restoring the right token lets it reconnect on its own. -
New response headers:
Referrer-Policy: no-referrer(the desktop URL carries the token, so an outbound link must not leak it inReferer), plusX-Frame-Options: DENYandContent-Security-Policy: frame-ancestors 'none'(GET /is public so login can bootstrap, but it must not be embeddable — an attacker page cannot read across origins, yet could otherwise clickjack a browser that already holds a token). -
Error shapes: the
disabled_no_tokenandlaunch_disabled_no_token403s are gone. Everything answers401 auth_required, which is what the UI and the mods already match on.
webterm_token.json is created 0600 on POSIX. Windows has no POSIX file
mode: the file inherits the containing directory's ACL, so on a shared
Windows host make sure the broker's working directory is not readable by other
accounts. The file is git-ignored either way.
If the directory is not writable the broker still starts, but with an
ephemeral token: it changes on every restart, --print-token cannot
recover it, and terminals do not survive a restart. That case warns loudly on
every start.
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