1# Configuration
2
3vev reads `~/.config/vev/config` (`$XDG_CONFIG_HOME` is respected).
4
5- No file means defaults.
6- Changes apply live as soon as the file is saved.
7- `#` starts a comment at the start of a line or after a space, except inside a quoted word. The file must be UTF-8 and at most 1 MiB; otherwise vev logs a warning and uses the defaults.
8- Exception: `web.listen` and `web.origin` need a gateway restart. See [browser terminal](web-terminal.md#listener-and-public-origin).
9- Invalid values log a warning and fall back to the default.
10
11The full list with defaults:
12
13```text
14# Browser gateway: HTTP listener and browser-facing origin, read at startup.
15web.listen = 127.0.0.1:8778
16web.origin = http://127.0.0.1:8778
17
18# Theme: auto follows the client; dark/light use neutral built-in defaults.
19theme = auto
20# In auto mode with palette inheritance enabled, infer a terminal accent.
21theme.palette = on
22# Accent policy: auto or one exact ANSI slot number from 0 through 15.
23theme.accent = auto
24
25# Palette placement: auto, center, top-left, top, top-right, left, right,
26# bottom-left, bottom, or bottom-right.
27palette.anchor = center
28
29# One floating terminal per tab. An empty command uses the normal shell.
30floating.command =
31floating.width = 80%
32floating.height = 80%
33
34# Let directional keyboard focus continue past a pane edge. Both default off.
35nav.overflow-tabs = off
36nav.overflow-sessions = off
37
38# Show the focused pane's terminal title in tab labels; off keeps the process name only.
39tabs.terminal-title = on
40
41# Remove a numbered (ephemeral) session when its last client exits.
42ephemeral.close-on-exit = on
43
44# Use the kitty keyboard protocol when the terminal supports it (enables Ctrl+1..9).
45keyboard.kitty-protocol = on
46
47# Outer terminal colors: auto (detect), truecolor, 256, 16, or mono.
48terminal.colors = auto
49
50# Draw typed characters on remote sessions before the server echoes them:
51# adaptive (only on a slow link), always, or never.
52echo.predict = adaptive
53
54# Rebindable actions. Leave a line out to keep its built-in binding.
55open-palette = alt+space
56toggle-floating-pane = alt+f
57jump-attention = alt+a
58focus-pane-left = alt+h
59focus-pane-right = alt+l
60focus-pane-up = alt+k
61focus-pane-down = alt+j
62# Optional pane rearrangement actions are unbound by default.
63# consume-or-expel-pane-left = alt+H
64# consume-or-expel-pane-right = alt+L
65# grow-pane-width, shrink-pane-width, grow-pane-height, shrink-pane-height,
66# and equalize-panes are also unbound by default.
67switch-tab-1 = alt+1
68# ... through switch-tab-9 = alt+9
69
70# Per-pane scrollback: decimal MB; zero disables history.
71scrollback.megabytes = 50
72# Optional additional line ceiling; zero means byte-only retention.
73scrollback.lines = 10000
74
75# Processes relaunched when a named session is restored. Empty disables relaunch.
76snapshot.restore_processes = vi,vim,nvim,emacs,man,less,more,tail,top,htop,btop,claude,codex,pi,opencode
77
78# Optional right bar anchors: commands run on the daemon host. Empty disables an anchor.
79bar.top-right =
80bar.bottom-right =
81bar.interval = 5s
82# Fill the top and bottom bars with the theme surface; off keeps the terminal background.
83bar.background = on
84
85# Command palette codes: 2-3 letters or digits.
86code.new-tab = CNT
87code.new-session = CNS
88code.create-ephemeral-session = CES
89code.close-tab = CLT
90code.split-right = SPR
91code.split-left = SPL
92code.split-up = SPU
93code.split-down = SPD
94code.consume-or-expel-pane-left = MPL
95code.consume-or-expel-pane-right = MPR
96code.stack-pane = STP
97code.toggle-stack = TFS
98code.close-pane = CFP
99code.focus-pane-left = FPL
100code.focus-pane-right = FPR
101code.focus-pane-up = FPU
102code.focus-pane-down = FPD
103code.resize-pane = RSZ
104code.grow-pane-width = GPW
105code.shrink-pane-width = SPW
106code.grow-pane-height = GPH
107code.shrink-pane-height = SPH
108code.equalize-panes = EQP
109code.move-pane = MFP
110code.move-tab = MAT
111code.next-tab = NXT
112code.previous-tab = PVT
113code.back-session = BCK
114code.jump-recent-session = JRS
115code.session-picker = SSP
116code.visual-mode = VIS
117code.toggle-floating-pane = TFP
118code.rename-session = RNS
119code.rename-tab = RNT
120code.detach = DET
121code.notifications = NTC
122code.yank-last-notification = YLN
123```
124
125## Scrollback
126
127| Key | Range | Default | Zero means |
128|---|---|---|---|
129| `scrollback.megabytes` | 0–4096 MB | 50 | no history |
130| `scrollback.lines` | 0–1,000,000 | 10,000 | no line limit, bytes only |
131
132- Limits are per pane, including hidden floating panes.
133- They count uncompressed history, not process memory.
134- A reload applies to existing panes right away. Lowering a limit drops the oldest rows.
135- Idle panes compress old history in the background. This saves memory but does not raise the limit.
136
137## Ephemeral sessions
138
139With `ephemeral.close-on-exit = on` (default), a numbered session is removed once its last client is gone for good:
140
141- The client process ends (terminal closed, SIGHUP, or SIGTERM). The client tells the daemon on a best-effort basis; if that message is lost, the rule below applies.
142- A client that lost its connection does not reconnect before the resume window (15 minutes) expires.
143
144The session stays while any other client is attached. A detach (keybinding, palette, or picker switch) keeps it, and so does a network drop within the resume window. Named sessions are never affected. Set `off` to keep numbered sessions until you kill them.
145
146Closing the terminal of a client running inside SSH also sends SIGHUP, so a dropped SSH connection removes the session. Use a named session for work you want to resume.
147
148## Development environments
149
150Set `VEV_ENV=<name>` to move every vev file into `.dev/<name>/` under the current directory. Use it to test a build without touching your real sessions.
151
152```sh
153VEV_ENV=dev go run .
154VEV_ENV=dev go run . kill --sessions
155rm -rf .dev/dev
156```
157
158- Name: up to 64 letters, digits, `.`, `_`, or `-`, starting with a letter or digit.
159- The same name shares one daemon. Use different names to run builds side by side.
160- Config, sessions, hosts, snapshots, and logs are isolated.
161- If the socket path gets too long, sockets move to `/tmp/vev-<uid>-<hash>`. Everything else stays in `.dev/<name>/`.
162- It is not a sandbox: pane processes see your real system.
163
164## Remote hosts
165
166```sh
167vev host add user@host                    # add a host (QUIC, the default)
168vev host add --transport ssh user@host    # add a host that uses SSH only
169vev host rm user@host                     # remove it
170vev host list                             # show hosts and their status
171```
172
173- `--transport quic|ssh` selects the carriage. `quic` (default) opens a direct QUIC connection bootstrapped over SSH; `ssh` carries everything over SSH, for networks that block UDP.
174- A host keeps the transport it was added with. To change it, run `vev host rm` and then `vev host add` again; adding it with a different transport is refused.
175- The broker stores hosts in `~/.local/state/vev/broker/state/state.json`.
176- Hosts connect over SSH, so your SSH config (aliases, keys) applies.
177- Remote sessions appear as `session@host` in `vev ls --all` and in the picker.
178
179### Warm remote transports
180
181After you leave a remote, vev keeps its connection open for a while. Going back is then instant: no new SSH login or QUIC handshake.
182
183Configure this in `~/.config/vev/broker.json`. The file is created on first use and read when the broker starts.
184
185```json
186{
187  "marker": "vev.broker.offline/v1",
188  "registrations": [],
189  "warmTransports": 8,
190  "warmIdleTimeout": "off"
191}
192```
193
194- `warmTransports`: how many idle connections to keep (0–64, default 8). The oldest one closes first. `0` disables it.
195- `warmIdleTimeout`: close an idle connection after this long, such as `5m` (max `24h`). Default `off`: no time limit.
196
197Warm connections never keep the broker running. Each open QUIC connection, warm ones included, sends a small keepalive every 2 seconds so mobile and NAT paths stay open; on battery, set `warmIdleTimeout` to close idle ones.
198
199## Logs and durable state
200
201| What | Where |
202|---|---|
203| Logs (JSON lines, e.g. `vev-daemon.log`) | `~/.local/state/vev/` |
204| Sessions and snapshots | `~/.local/state/vev/` |
205| Broker hosts and logs | `~/.local/state/vev/broker/` |
206| Socket and lock | `$XDG_RUNTIME_DIR/vev/` |
207
208`$XDG_STATE_HOME` is respected. Set `VEV_LOG=debug|warn|error` to change the log level (default `info`).
209
210If the daemon refuses to start because its session data is broken, do not edit the files. See [durable session recovery](durable-session-recovery.md).
211
212## Theme
213
214| Setting | Effect |
215|---|---|
216| `theme = auto` | Follow your terminal's colors and light/dark mode. |
217| `theme = dark` / `light` | Neutral built-in colors. Ignores `theme.palette` and `theme.accent`. |
218| `theme.palette = off` | Neutral colors, no accent. |
219| `theme.accent = auto` | Pick an accent from your terminal's ANSI colors (blue if unsure). |
220| `theme.accent = 0`–`15` | Use exactly that ANSI color as the accent. |
221| `bar.background = off` | Keep the terminal background behind the top and bottom bars (useful with a transparent terminal). Tabs and recent sessions keep their colors. No effect on 16-color and mono terminals, where bars already use it. |
222
223- vev only colors its own UI (bars, borders, palette). Pane content is never recolored.
224- Tinted backgrounds need a truecolor or 256-color terminal. On 16-color and monochrome terminals vev uses bold, reverse, and faint instead. See [terminal colors](terminal.md#colors).
225- `terminal.colors` forces the color mode of your terminal (`auto`, `truecolor`, `256`, `16`, `mono`). `VEV_COLORS` overrides it. See [terminal colors](terminal.md#colors).
226- vev follows light/dark switches your terminal reports. It cannot see palette changes the terminal does not report.
227
228## Bindings
229
230Valid keys: `alt+<char>`, `alt+space`, `alt+left/right/up/down`, `alt+1` to `alt+9`.
231
232- Setting an action replaces all its default keys. For example, setting `focus-pane-left` removes Alt+Left too.
233- Tab switching works with AZERTY and other layouts without extra config.
234- Ctrl+1 to Ctrl+9 (recent sessions) are fixed and not rebindable. Turn them off with `keyboard.kitty-protocol = off`.
235- `alt+[` is not supported: terminals use it for escape sequences.
236- Cmd/Super is not supported. Map it in your terminal to `ESC` + a character, then bind `alt+<char>` in vev.
237
238## Pane consume or expel
239
240Moves the focused pane between columns, like the Niri window manager. It has no default key: use palette codes `MPL` / `MPR`, or bind `consume-or-expel-pane-left/right`.
241
242- A pane alone in its column joins the column next to it.
243- A pane sharing a column leaves it and becomes its own column.
244- Works only with column layouts. Nested mixed splits are not supported.
245
246## Navigation overflow
247
248Both are `off` by default.
249
250- `nav.overflow-tabs = on`: Alt+h/l at the edge of the tab moves to the next tab.
251- `nav.overflow-sessions = on`: Alt+k/j at the edge moves to the next session (alphabetical).
252
253No wrap-around. Only keyboard focus overflows, never the mouse or floating panes.
254
255## Copy mode
256
257Scroll up with the mouse to enter. Scroll back to the bottom to leave.
258
259| Key | Action |
260|---|---|
261| `h` `j` `k` `l` | move |
262| `w` `b` `e` | word motions |
263| `v` or Space | start selection |
264| `y` or Enter | copy |
265
266With the mouse: drag to select, double-click to select a word.
267
268```ini
269# Unicode whitespace always separates words.
270# The default is " -_@".
271copy.word-separators = " -_@"
272# Disable animated wheel scrolling (default: off).
273copy.reduce-motion = off
274```
275
276- `copy.word-separators = ""` uses only whitespace.
277- `copy.reduce-motion = on` scrolls three rows per wheel step, without animation.
278
279## Responsive overlays
280
281Below 80 columns, popups (palette, picker, floating terminal, prompts) become full-width drawers at the bottom of the screen. The background dims while a popup is open.
282
283## Palette anchor
284
285- Default: centered.
286- `palette.anchor = auto`: bottom bar from 80 to 95 columns, right-side rail from 96 columns.
287- Any other value places it at that spot. Below 80 columns it is always a bottom drawer.
288
289## Floating terminal
290
291- `floating.command` runs through your shell. Changes apply on the next launch.
292- Below 80 columns, the terminal takes the full width and keeps `floating.height`.
293- Floating terminals are not restored after a daemon restart.
294- Each session keeps one pre-started shell ready. The first tab that opens its floating terminal takes it, and the session starts the next one in the background. A shell started in another directory is replaced by a fresh one in the tab's directory.
295
296## Bar anchors
297
298`bar.top-right` and `bar.bottom-right` show the output of a command in the bar. Both are off by default.
299
300- The command runs on the daemon host every `bar.interval` (minimum `1s`), with the same environment as your panes.
301- vev shows the first line of output, without colors. On failure it keeps the last good value.
302- Scripts receive `VEV_ANCHOR`, `VEV_SESSION`, `VEV_TAB`, `VEV_PANE`, `VEV_PANE_CWD`, `VEV_COLS`, and `VEV_CLIENT_PID`.
303- `VEV_CLIENT_PID` is the PID of a local attached client, so a script can find the terminal window and monitor showing the bar. With several clients attached, it is the one whose terminal has focus, else the first local one. It is empty when only remote clients (SSH or another machine) are attached, since their process lives elsewhere.
304- Failures are logged with the exit code and stderr. Exit 127 means "command not found".
305
306Release installs ship two example scripts: `vev-bar-top-right` and `vev-bar-bottom-right`. Under the NeferWL compositor, the first one also shows the client's monitor and workspaces (`DP-2 [x][ ][ ]`); set `bar.interval = 1s` to follow workspace changes. The second one runs `git status` on every refresh; raise the interval on large repositories.