diff options
| author | Franz Bettag <franz@bett.ag> | 2026-04-28 19:11:11 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-04-28 20:11:11 +0300 |
| commit | 5baf231e076ed96bb2aaba245eb53ad0e4501d76 (patch) | |
| tree | a89d28ad26b26f8b8e519106dc304d4e54d3b39e /SOCKET_API.md | |
| parent | 22d7bef5680a1d55c28ff6246518d96487e95d5e (diff) | |
Add named persistent sessions (#57)
* feat: add named persistent sessions
* feat: add session management commands
* fix: tighten named session stop and override precedence
* fix: handle session help and stop test race
* test: isolate default session env test
---------
Co-authored-by: Ogulcan Celik <ogulcancelik@gmail.com>
Diffstat (limited to 'SOCKET_API.md')
| -rw-r--r-- | SOCKET_API.md | 18 |
1 files changed, 13 insertions, 5 deletions
diff --git a/SOCKET_API.md b/SOCKET_API.md index b9da2efb..ea834e14 100644 --- a/SOCKET_API.md +++ b/SOCKET_API.md @@ -23,13 +23,21 @@ important difference: `pane.run` and `wait agent-status` are **cli conveniences* - request/response: send one json request per line, read one json response per line - subscriptions: send `events.subscribe`, receive an ack, then keep the same connection open and continue reading pushed events +named sessions are runtime/socket namespaces, not replacements for herdr workspaces. each named session has its own server sockets and persistent runtime state while config remains global. + socket path resolution order: -1. `HERDR_SOCKET_PATH` -2. `$XDG_RUNTIME_DIR/herdr.sock` -3. `$XDG_CONFIG_HOME/herdr/herdr.sock` -4. `$HOME/.config/herdr/herdr.sock` -5. `/tmp/herdr.sock` +1. explicit `herdr --session <name>`: + `$XDG_CONFIG_HOME/herdr/sessions/<name>/herdr.sock` or `$HOME/.config/herdr/sessions/<name>/herdr.sock` +2. `HERDR_SOCKET_PATH` +3. `HERDR_SESSION=<name>`: + `$XDG_CONFIG_HOME/herdr/sessions/<name>/herdr.sock` or `$HOME/.config/herdr/sessions/<name>/herdr.sock` +4. default session path: + `$XDG_CONFIG_HOME/herdr/herdr.sock` or `$HOME/.config/herdr/herdr.sock` + +this means `HERDR_SOCKET_PATH` remains an exact low-level socket override, but an explicit cli `--session <name>` still wins when a command runs inside a pane that inherited `HERDR_SOCKET_PATH`. + +session names may contain ASCII letters, numbers, `.`, `_`, and `-`. `default` is reserved for the default session. use `herdr session list`, `herdr session stop <name>`, and `herdr session delete <name>` to inspect and manage session namespaces. `session delete` refuses running sessions and does not delete the default session. ## request and response envelopes |