1# Browser terminal
2
3```sh
4vev --web-daemon
5```
6
7This starts a background web server on `127.0.0.1:8778` and prints a private link. Open it in a browser to get the normal vev UI: palette, tabs, and splits.
8
9- Each browser tab is its own client. Closing the page detaches; shells keep running.
10- Reloading creates a **new** session. Find old ones with the session picker (`SSP`) and close the ones you don't need.
11- Running the command again prints the same link.
12
13## Access from another machine
14
15vev serves plain HTTP. For HTTPS, put a reverse proxy in front of it (for example Caddy, nginx, or a NetBird app).
16
17```sh
18vev --web-daemon --web-listen 127.0.0.1:8778 \
19  --web-origin https://terminal.example.internal
20```
21
22Or in `~/.config/vev/config`:
23
24```ini
25web.listen = 127.0.0.1:8778
26web.origin = https://terminal.example.internal
27```
28
29- `web.listen`: IP and port to listen on, such as `100.64.0.10:8778` or `[::1]:8778`. No hostnames.
30- `web.origin`: the URL users type in the browser, without a path. Required when not listening on loopback.
31- Flags override config. Restart the gateway to apply changes; shells survive.
32
33The proxy must:
34
35- keep the original `Host` and `Origin` headers,
36- forward WebSocket upgrades,
37- serve vev at the root path (no `/vev/` prefix).
38
39> [!WARNING]
40> Access to this page is access to your shell. Prefer loopback or one private IP. Avoid `0.0.0.0` unless a firewall restricts access.
41
42## Controls
43
44| Input | Action |
45|---|---|
46| Alt+Space or **Palette** button | command palette |
47| Alt+h/j/k/l | focus pane |
48| Alt+1…9 | switch tab |
49| Click | focus pane |
50| Shift + wheel | scroll 10× faster |
51| Ctrl+Shift+F6 | move focus out of the terminal to the Palette button |
52
53- The terminal fits the window, up to 512×256 cells.
54- On touch devices, **Select** allows native text selection and **Keys** opens the keyboard.
55- Your browser or window manager may catch some shortcuts first. The Palette button avoids the common Alt+Space conflict.
56
57Not supported yet: browser scrollback, touch scrolling, copy-mode clipboard export, Kitty images, OSC 52, and full emoji fidelity.
58
59## Security
60
61- The access token is random, kept only in memory, and gone when the gateway stops.
62- The link carries it once; the page then swaps it for an HttpOnly cookie.
63- `vev --web-renew-token` revokes all links and browser sessions and prints a new link. Shells keep running.
64- Host and Origin checks, a strict Content Security Policy, and input limits protect the endpoint.
65- Everything is embedded in the binary. No CDN or frontend framework.
66
67## Stop the gateway
68
69The gateway is a separate process. Stopping the session daemon does not stop it. Send it `SIGTERM`.
70
71## Testing a build
72
73Use an isolated profile so tests don't touch your real sessions:
74
75```sh
76go build -o .dev/vev-web .
77VEV_ENV=web-visual .dev/vev-web --web-daemon
78VEV_ENV=web-visual .dev/vev-web ls
79```
80
81Keep the printed link out of screenshots.
82
83`scripts/web-visual-smoke.cjs` and `scripts/web-access-smoke.cjs` run Playwright checks. Set `PLAYWRIGHT_MODULE`, `VEV_BINARY`, `VEV_ENV=web-visual`, and optionally `CHROMIUM_PATH`. Run them only against an isolated profile: they create sessions and revoke access.