toowl

Documentation

Browser access

Open a toowld session in any browser over a single, scoped, expiring URL — with optional built-in TLS.

Any toowld session can be opened in a web browser — a live, resizable terminal with full scrollback, served by the daemon itself. No extra process, no tunnel software: one command mints a URL, you open it.

Enable the HTTP server

The browser surface is opt-in. Start toowld with TOOWLD_HTTP_BIND set to an address it should listen on: 

TOOWLD_HTTP_BIND=127.0.0.1:8721 toowld

A loopback bind (127.0.0.1) is the safe default — reach it from another machine over an SSH tunnel, or enable TLS (below) for a network bind. A non-loopback bind without TLS is refused unless you set TOOWLD_HTTP_INSECURE=1, because browser tokens travel in the URL and would otherwise cross the network in cleartext.

Get a URL

toowl roost web mints a token scoped to one session and prints a ready-to-click URL: 

$ toowl roost web my-session
Open in a browser (multi-use until expiry):
  http://127.0.0.1:8721/web/2f9c…/?token=ABCD…
  expires in 86400s

The token is multi-use (refresh, reconnect, and a second tab all work), bound to that one session, scoped to attach / write / snapshot / resize (never kill), and expires (24 h by default; pass --expires 1h / 30m / 7d). Anyone with the URL can drive that session until it expires, so treat it like a password. The matching one-shot flow is toowl roost share (a single-use token for the native clients).

What the browser terminal does

  • Replays recent scrollback on connect — the terminal isn’t blank.
  • Fits and resizes the remote PTY to the window (full-screen apps lay out correctly).
  • Streams keystrokes and output over a WebSocket; works on mobile.

TLS

For a network bind, terminate TLS in the daemon by pointing it at a PEM certificate chain and private key: 

TOOWLD_HTTP_BIND=0.0.0.0:8721 \
TOOWLD_HTTP_TLS_CERT=/etc/toowl/cert.pem \
TOOWLD_HTTP_TLS_KEY=/etc/toowl/key.pem \
  toowld

The URL then uses https:// (and the WebSocket wss://), and the non-loopback bind is allowed. A TLS-terminating reverse proxy in front of a loopback bind works equally well.

WebSocket remotes for native clients

The same server exposes a JSON-RPC control channel at /v1/rpc, so the desktop and TUI clients can reach a daemon over ws:// / wss:// — see Remote machines. That channel is token-only (a WebSocket carries no OS or SSH trust), so each connection authenticates with a share token.

Security model

  • Every token is bound to a single session and a fixed set of operations; daemon-control routes are refused.
  • The page sets a Content-Security-Policy, X-Frame-Options: DENY, and Referrer-Policy: no-referrer; xterm.js loads from a pinned CDN with Subresource Integrity.
  • Token-driven writes, kills, and attaches over the web surface are recorded in the audit log.