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