hive

The agent infrastructure for agents that don’t clock out

Run them anywhere. Leave them running.

https://github.com/user-attachments/assets/bd7b9d6e-d0f5-43d7-9889-34c1a3fb0c9e

Vision

Start an agent and walk away. Hive keeps its environment alive when your terminal closes, your SSH connection drops, or your laptop goes to sleep. Come back later and pick up where you left off.

• One machine, many agents. Each agent gets its own workspace, terminal and context, so a hundred of them can work without stepping on each other.
• See everything working. A terminal multiplexer built for agents: tabs of split panes with live agent screens, and an Overview of which agents are running, waiting, done or failed, so you don't have to open a dozen terminals.
• Bring your own agent. Claude Code, Codex, OpenCode, Cursor, your own agent, whatever comes next. Hive doesn't replace them; it gives them somewhere to live.
• Agents that operate agents. The same interface you use (creating workspaces, launching tasks, reading output) is available to agents themselves, so the infrastructure becomes part of the agent's toolkit.
• Built for the background. Long builds, large migrations, test suites, research and parallel tasks: work that takes longer than a terminal session.

Status

Hive is at v1.0 release candidates and built in public. The wire API, the CLI, the configuration keys and the Go SDK are frozen: 1.x only adds to them (compatibility policy). Documentation lives at hive.admir-saheta.com/docs; start with the quick start, or the migration guide if you come from herdr.

Running it for real: what works with what across releases (compatibility matrix), upgrading and recovery, operations (backups, retention, diagnosing a failed session, remote runtimes, which features are stable), and the threat model.

Quick start

Install the latest macOS or Linux release with:

curl -fsSL https://hive.admir-saheta.com/install.sh | sh

The installer places hive in ~/.local/bin by default. Set HIVE_INSTALL_DIR to choose another directory, HIVE_CHANNEL=preview for release candidates, or HIVE_VERSION for a given release. Or:

brew tap admirable-oss/tap && brew install hive-agents  # Homebrew CLI formula
brew install --cask admirable-oss/tap/hive               # macOS cask
nix run github:admirable-oss/hive              # Nix (or nix profile install)
go install github.com/admirable-oss/hive/cmd/hive@latest

On Windows 10 1809 or later (amd64 or arm64), in PowerShell:

irm https://raw.githubusercontent.com/admirable-oss/hive/main/distribution/install.ps1 | iex

Agents there run in pseudo consoles (ConPTY); docs/platforms.md has the support matrix, where Hive keeps its files on each system, and what differs on Windows.

Release binaries are signed, and hive update checks the signature (SECURITY.md). To build from source, Go 1.26+ is required.

make build          # or: go build -o hive ./cmd/hive

./hive demo         # starts the daemon on demand, then launches four demo agents
./hive              # open the multiplexer
./hive daemon install   # optional: start the daemon at login, restart it if it crashes

The multiplexer works like tmux: press the prefix, Ctrl+B, then a key.

A split or popup starts in the directory its pane is working in (after a cd, too); a new tab starts at the environment's root. The mouse works too: click to focus, drag borders, select to copy, scroll into history. The keystrokes guide lists every binding and how to change them.

CLI

Add --template '<Go template>' to format a command's JSON output for scripts (hive env list --template '{{range .}}{{.id}}{{"\n"}}{{end}}'). Every command that talks to the daemon starts it if it is not running (turn this off with daemon.autostart = false). Add --json to any command for machine-readable output. Exit codes: 0 success, 1 error, 2 bad command line, 3 daemon not running.

Configuration

Hive reads ~/.config/hive/config.toml (or $XDG_CONFIG_HOME/hive/config.toml, or $HIVE_CONFIG). Every key is optional; hive config init writes a commented file with the defaults:

[daemon]
autostart = true            # start the daemon when a command needs it
shutdown_timeout = "15s"    # how long stopping waits for agents to exit

[log]
level = "info"              # debug | info | warn | error  (HIVE_LOG overrides)
format = "text"             # text | json
max_size_mb = 10            # the daemon log rotates at this size…
max_backups = 3             # …and keeps this many old files

[process]
stop_grace = "3s"           # SIGTERM → SIGKILL delay when stopping an agent

[terminal]
default_width = 220         # size of a new agent terminal
default_height = 50
scrollback_mb = 10          # history kept per agent (lines that scrolled off its screen)

[session]
restore = true              # after a reboot, start panes again where they were working…
resume_agents_on_restore = true  # …and resume agents' conversations (claude --resume <id>)
replay_history = false      # show panes' earlier text again (keeps screen text on disk; see the persistence guide)

[retention]
exited_processes = "168h"   # keep ended processes' records and logs this long
process_log_mb = 50         # rotate each agent's output log at this size

[remote]
ssh = "ssh"                 # how other machines are reached (~/.ssh/config applies)
frame_budget_kb = 48        # screen updates a remote daemon sends this client, KiB/s
image_budget_kb = 1024      # how fast a pasted image is sent to a remote daemon, KiB/s

[images]
max_kb = 5120               # largest image pasted with prefix I
keep = "1h"                 # how long images saved for agents that take a path are kept
render = "auto"             # images agents print: auto | cells | text | off

[plugins]
allow = []                  # optional capabilities granted to every plugin that asks
deny = []                   # capabilities no plugin gets
isolation = "auto"          # sandbox plugins that support it | standard | strict
restart_limit = 5           # crashes within restart_window before a plugin is given up on

[ui]
sidebar = true              # show environments and agents beside the panes
sidebar_width = 28
mouse = true                # click, drag borders, select to copy, scroll
clipboard = "auto"          # auto | osc52 | local | off

[theme]
name = "auto"               # auto | hive | hive-light | catppuccin | catppuccin-latte | tokyo-night | gruvbox | nord | terminal | custom

[keys]
prefix_keys = ["ctrl+b"]    # bindings per mode in [keys.<mode>]; see the keystrokes guide

[update]
channel = "stable"          # stable | preview (release candidates too)

The configuration reference describes every key.

Unknown keys and invalid values are reported as warnings and fall back to the defaults, so a typo never stops the daemon that keeps your agents alive. A file that is not valid TOML is an error, and the daemon refuses to start with it. hive config validate checks a file and exits non-zero on any problem.

Data lives in ~/.hive. Set HIVE_HOME to use another directory, for example to run an isolated daemon for testing.

Architecture

Hive is a single binary with three roles:

• a shim per agent (hive __shim), which owns the agent's PTY, terminal emulator and logs, and outlives everything except hive stop;
• a daemon that owns environments and supervises agents through their shims;
• clients (the CLI and the multiplexer UI) that talk to the daemon over a unix socket.

Closing a client never touches an agent. Stopping, crashing or upgrading the daemon doesn't either: the next daemon re-attaches to the shims (ADR 0006).

cmd/hive ──────────── CLI composition root: builds one `app` (paths, config, client); cobra commands
 │
 ├── tui ──────────── multiplexer UI (mux app, compositor, keymap, copy mode, themes); depends only on client
 ├── daemonctl ────── start the daemon detached (autostart), install launchd / systemd services
 ├── config ───────── config.toml: defaults, forgiving validation, rendering
 ├── client ───────── protocol 2 over one connection (falls back to protocol 1)
 │        ╎
 │        ╎  unix socket (0600) · newline-delimited JSON
 │        ╎
 └── runtime ──────── daemon composition root: wires modules, serves the socket, owns agent lifetimes
       ├── process ── supervises agents: start, monitor, stop, recover / adopt, logs
       │     ├── environment ── persistent workspaces
       │     └── terminal ───── sessions, viewers, size arbitration, attach / frames / snapshot
       │            └── shim ──── one process per agent: PTY + emulator; adopted after restarts
       │                   ╎
       │                   ╎  run/<id>/shim.sock · protocol 2
       ├── event ──── event bus behind `events.subscribe`
       └── vt ─────── terminal emulation (x/vt), frames codec, ANSI painter, scrollback
           protocol · jsonfile · pgroup · platform · logging · buildinfo   (leaves)

Dependencies only point down. Leaf packages know nothing about Hive's domain, and no package imports one above it. The rule is enforced by depguard in make lint.

Following a call from main to the OS

Every layer is reached through an explicit call, so you can read the code top to bottom:

hive ps start -t dev -- claude
  main.execute                      cmd/hive/main.go      → newApp (config, paths, client), cobra root
  root PersistentPreRunE            cmd/hive/root.go      → app.ensureDaemon: ping, or autostart via daemonctl.Spawn
  newProcessStartCmd (RunE)         cmd/hive/cmd_process.go
  client.ProcessStart → call()      internal/client       → protocol.Stream.Send
  ─────────────── socket ───────────────
  runtime.Server.accept             internal/runtime      → protocol.Serve(conn) (checks the protocol version)
  protocol.Router.Handle            internal/protocol     → "process.start"
  protocol.Method[StartRequest]     decodes params once, encodes the result
  process.service.Start             internal/process      → Environments.Get (port)
  process.service.launch            → terminal.Service.Open → shim.Launcher.Open: spawn `hive __shim` (setsid)
  shim.Run (in the shim process)    internal/shim         → PTYFactory.Open → creack/pty, vt.Terminal
  process.service.monitor           Remote.Wait (shim.wait) → persist the final state → Remote.Release

On disk

~/.hive/
  hive.sock                                  daemon socket (0600, in a 0700 directory)
  hive.pid                                   daemon PID; flock-ed while the daemon runs (one daemon per root)
  logs/daemon.log[.1…]                       structured daemon log, rotated by size
  logs/daemon.stderr                         the daemon's stderr from its last start (start-up errors)
  session.json                               the latest workspace snapshot (restore after a reboot)
  snapshots/session-<time>.json              the 48 before it
  history/<pane>.txt                         panes' recent text, only with session.replay_history
  machines.json                              saved machines (hive machine), shared by every session
  identity.json                              this installation's identity key (pairing pins it), 0600
  plugins/<id>/  plugins/registry.json       installed plugins (shared by every session); plugins/.data/<id>/ their data,
                                             .config/<id>/ their settings, .cache/<id>/ their caches
  <session>/p/<hash>.sock                    each running plugin's own daemon socket, scoped to its capabilities
  observer.sock                              the observer socket: read-only, token-authenticated (0600)
  observers/credentials.json  audit.log      observer credentials (token hashes only) and who used them
  web/                                       the web observer: runtimes.json, tokens/ (0600), access.json (hashes only),
                                             push.json (devices, notification settings), vapid.key (0600),
                                             audit.log, web.log, web.sock (its admin socket)
  logs/plugins/<id>.log                      what each plugin's commands printed
  ssh/                                       shared SSH connections' sockets (ControlMaster)
  run/<process-id>/                          one shim per live agent (0700)
    spec.json  state.json                    what it runs; running / exited + exit code
    shim.sock  shim.log  shim.stderr         its socket (0600) and its own logs
  environments/<env>/
    environment.json
    workspace/                               where the env's agents run
    processes/<id>/
      process.json                           lifecycle record (written atomically)
      stdout.log  stderr.log                 output, private to the user (PTY output goes to stdout.log; rotates to .1)

Wire protocol

One JSON object per line. Requests carry type, id, method and params; each response carries the same id with either result or error: {code, message}. Error codes are invalid_request, unknown_method, invalid_params, not_found, internal_error, unsupported_version, unsupported and unavailable.

• Protocol 1 is the default: one request, one response, in order. Hand-written clients (nc) use it. A request may open a pipe that takes over the rest of the connection.
• Protocol 2 starts with {"type":"hello","version":"2","params":{"client":…}}. The server answers with a welcome listing its methods and capabilities. From then on, requests run concurrently and any number of pipes share the connection: the response that opens one carries a stream ID, and its bytes travel as {"type":"data","stream":…,"data":<base64>} until a close. The CLI and the multiplexer speak protocol 2, and fall back to protocol 1 against an older daemon.

The observer socket (observer.sock) speaks the same protocol 2 but
offers only observe.* methods, all read-only, after observe.auth with
an observer token (observers).

Screens never travel as raw output. Each agent's terminal is emulated in its shim, and viewers get frames computed from the current screen when they are ready for one. A slow viewer gets fewer frames, never a corrupted screen, and a late one starts with an exact keyframe. process.logs returns a size-capped tail in one reply (truncated: true when cut); process.logs.stream sends logs of any size.

Design principles

Protocol-Oriented Programming (POP)

Hive is designed contracts first. Each layer depends on a small interface (a protocol, in the Swift sense), and concrete types are plugged in at a single composition root.

• The consumer owns the interface. process doesn't import the whole environment service. It declares Environments{ Get } and Terminals{ Open } and accepts anything that fits. The runtime declares Supervisor{ Recover, StopAll } for the same reason.
• Small surfaces. protocol.Handler has one method, and Store, Runner, Factory and ListenerFactory have a handful each. Small contracts are cheap to fake, so most tests need no network or processes.
• Composition instead of inheritance. Go has no class inheritance. Where you might reach for it, Hive embeds an interface and overrides one method. runtime.envGuard embeds environment.Service and overrides only Delete, which stops the environment's agents first. process.sessionHandle embeds a terminal.Session and adapts it into a Handle.

Patterns you'll find

Conventions

• One file per role: pkg.model.go (types), pkg.service.go (contract and implementation), pkg.store.go (port), pkg.filesystem_store.go (adapter), pkg.protocol.go (wire handlers), pkg.module.go (wiring and package doc), pkg.error.go.
• Comments explain why, not what. Each package starts with a short doc comment, and non-obvious decisions are commented where they happen.
• Minimal dependencies. Bubble Tea and Lip Gloss (UI), creack/pty (terminals), cobra (CLI), go-toml (config), x/sys, godbus (the logind shutdown notice on Linux), and two small charmbracelet/x helpers. Everything else is the standard library. A new dependency needs an ADR.

Contributing

make check      # vet, lint (pinned golangci-lint), race tests with goleak, go.mod tidiness
make fuzz       # run the fuzz targets (protocol framing, config, manifests, graphics, discovery)
make vuln       # known vulnerabilities the code can reach (govulncheck)
make upgrade    # upgrade from every earlier 1.x release and back
make snapshot   # build release archives into ./dist

Tests sit next to the code or in a package's tests/ directory. Fakes for Store, Runner, Factory and client.Client let most tests run without real processes. Integration tests start a real daemon on a temporary socket, and the CLI's end-to-end tests run the real binary path, autostarting a daemon in a scratch HIVE_HOME. Every package checks for leaked goroutines.

See CONTRIBUTING.md for coding standards, GOVERNANCE.md for how decisions and releases are made (substantial changes start as an RFC), and architecture decisions for design decisions. Issues and pull requests are welcome. Please keep changes small, follow the file conventions above, and include a test with each bug fix.

Found a security issue? Please follow SECURITY.md instead of opening a public issue.

License

Apache 2.0