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

What 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`	Terminated	A clean start; the sessions are forgotten
Daemon crash, `kill -9`, reboot, sleep	Gone (a reboot ends all processes)	The sessions listed as lost (◌), with their label, agent and directory

A lost session's process is gone, but you can press Enter on it to relaunch the same command in the same directory, or x to forget it. Many agents can pick up their conversation: claude --continue, codex resume. 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 the Obsidian integration opens
`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_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 done

Upgrading

hive update         # installs the latest release next to the running hive
hive                # new windows use the new version straight away

A 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.