The Hive daemon, files and environment variables
What hived does, what survives a crash or reboot, where Hive keeps its files, the environment variables it reads and sets, upgrading and uninstalling.
What the daemon does
hived owns every session: the agent process, its terminal (PTY) and an emulator holding its screen and scrollback. The hive window only mirrors the sessions it shows and forwards your keys, which is why closing it stops nothing. The first hive command starts the daemon in the background (turn that off with [daemon] auto_start = false); one daemon serves every window and command of your user.
hive daemon status # running? version, pid, socket
hive daemon start
hive daemon stop # ends every session (asks first); Ctrl+Space R restores themWhat survives what
| Event | Agents | What you see |
|---|---|---|
| Close the window, detach, SSH drops | Keep running | Everything, as you left it, next time you run hive |
| The daemon goes away while a window is open | Depends on why (below) | The window keeps the last screen and reconnects on its own |
hive daemon stop, upgrade | Terminated (it lists them and asks first) | The sessions listed as ended (◌), ready to restore |
Daemon crash, kill -9, reboot | Gone (a reboot ends all processes) | The same: the sessions listed as ended (◌), with their label, agent and directory |
An ended session's process is gone, but Hive kept its command, directory, label and space. When you open hive it says how many ended; Ctrl+Space R restores them all, Enter on one relaunches just that one, and x forgets it. The agent that was running picks up its last conversation in that directory: Claude Code with --continue, Codex with resume --last. An agent you started from a terminal is run in that terminal again, which stays when the agent exits. Other agents start fresh. Sleep pauses agents rather than ending them; they carry on when the machine wakes. For agents that run overnight, use a machine that stays on and connect over SSH.
Where Hive keeps things
| What | Linux | Override |
|---|---|---|
| Config | ~/.config/hive/config.toml | HIVE_CONFIG |
| Socket and lock | $XDG_RUNTIME_DIR/hive/ (mode 0700) | HIVE_RUNTIME_DIR |
Logs (hived.log, hive.log) and sessions.json | ~/.local/state/hive/ | HIVE_STATE_DIR |
| Worktrees | ~/.local/share/hive/worktrees/ | [worktrees] dir |
macOS and Windows use their usual folders; hive doctor prints the actual paths. sessions.json holds session and workspace details (labels, commands, directories), never environment variables. Logs never contain environment variables or agent output. On Windows the daemon listens on a named pipe protected by a token instead of a socket.
Environment variables
Read by Hive
HIVE_CONFIG | Config file to use |
HIVE_RUNTIME_DIR | Directory for the socket and lock. Keep the path short: socket paths must fit in about 107 bytes |
HIVE_STATE_DIR | Directory for logs and session details |
HIVE_LOG | Log level, e.g. debug |
HIVE_DAEMON_BIN | The hived binary to start (default: next to hive, then PATH) |
NO_COLOR, COLORTERM, TERM | Colour detection, unless [theme] colors is set |
VISUAL, EDITOR | The editor e opens in the notes app |
HIVE_VAULT | The notes vault for hive notes and hive context. Hive sets it in sessions started in a space with a vault |
HIVE_INSTALL_DIR, HIVE_VERSION | For the install script and hive update: where to install, and which version |
Set for every session
HIVE=1 | The program runs inside Hive |
HIVE_SESSION_ID | The session's id |
HIVE_VAULT | The space's notes vault, when it has one |
HIVE_BIN_PATH | The hive binary, for report-agent |
TERM=xterm-256color, COLORTERM=truecolor | What the session's terminal supports |
Otherwise a session starts with the environment of the hive command that created it, plus the agent's env from the config.
A private instance
To try things without touching your real sessions, point Hive at scratch directories. It starts a separate daemon there:
export HIVE_RUNTIME_DIR=/tmp/hive-test HIVE_STATE_DIR=/tmp/hive-test/state HIVE_CONFIG=/tmp/hive-test/config.toml
hive
hive daemon stop # when doneUpgrading
hive update # installs the latest release next to the running hive
hive # new windows use the new version straight awayA running daemon keeps its version, and your sessions, until it stops. Most releases work with the old daemon; when one doesn't, hive says the protocol versions differ, and hive daemon stop (which ends your sessions) followed by hive starts the new one. On Windows, run the installer again.
Uninstalling
hive daemon stop
rm ~/.local/bin/hive ~/.local/bin/hived
rm -rf ~/.config/hive ~/.local/state/hive
# Worktrees in ~/.local/share/hive/worktrees may hold your work: check them first.On Windows: hive daemon stop, then delete %LOCALAPPDATA%\hive and the config and state folders hive doctor lists.
Something wrong or missing? Open an issue.