Architecture

System Overview

Hive has two operating modes:

Standalone mode (default): A single hived daemon manages sessions locally. Clients connect over WebSocket.

Cluster mode: a few hived nodes form a leaderless peer group. Every node is a co-equal authority: it owns the session processes it spawns, applies writes locally, and gossips each change to all peers. There is no leader, no election, and no quorum. A node going offline never stalls the rest of the cluster; on reconnect, anti-entropy merges any state that diverged while it was away.

                    Peer WS (port+1)
  +-----------+ <--------------------> +--------------+
  |  hived      |    gossip + merge      |  hived         |
  |  Node A   | <--------------------> |  Node B      |
  |           |                        |              |
  +-----+-----+                        +------+-------+
        | client WS :9178                      | client WS :9178
        |                                      |
  +-----v-----+                        +------v-------+
  |  rc CLI   |                        |  rc CLI      |
  +-----------+                        +--------------+

Components

Hive is made up of a few cooperating pieces:

• hived - the daemon. Owns and supervises agent and shell sessions, serves the client WebSocket protocol, persists session/task/history state, runs the task scheduler, sends notifications, and (in cluster mode) gossips state to peers.
• hive - the command-line client. Connects to a daemon over WebSocket to create, attach to, send to, list, and kill sessions, adopt running processes, and inspect the cluster.
• Desktop & mobile app - a cross-platform GUI with full CLI parity, talking to a daemon over the same WebSocket protocol.

All pieces speak the same JSON wire protocol (see Protocol); only terminal output uses a binary frame.

How it works

Sessions

A session wraps one running process - an agent CLI (SDK or interactive) or an arbitrary shell. The owning daemon assigns each session a UUID, supervises the process, and fans its output out to every attached client over the session's output stream. Two session modes exist:

• PTY: an interactive terminal; output is raw terminal bytes rendered by the client's terminal emulator, and keystrokes and resizes flow back to the process.
• SDK: a headless agent driven turn-by-turn; each prompt runs the provider CLI and streams structured JSON the client renders as a chat transcript. The provider's own conversation id is threaded across turns so context is kept.

In a cluster, the node a client connects to does not necessarily own a session it creates. An explicitly targeted session starts on the selected node; in the app, New Session and Quick New Session use the selected project's pinned node. If that node is offline, creation stops with an error instead of falling back to the connected node. A request without a node target starts on the connected node. Session metadata is then gossiped to all peers. Requests that must reach the live process, including claims, input, resize, and output subscription, are routed to the owning node.

When an operator assigns a custom session name, the owning daemon persists it for the live session and pushes the update to every connected client. This also updates clients connected through another cluster node, and clients that connect later receive the saved name with the session metadata.

Output streaming and resume

Each session has a bounded, replayable output stream. Clients subscribe to it live and can resume from a sequence cursor after a reconnect without losing output. See Transport & Resume for the replay ring, resume, and keepalive policy.

Persistence

Each daemon persists session metadata, tasks, and history to a local SQLite database in its platform data directory. On startup it restores sessions for history display without re-spawning processes; status changes are written back.

Task scheduler

A scheduler wakes on a fixed tick, runs any due tasks (one-shot, interval, or cron), and drives them as ordinary SDK sessions whose output streams to clients. See Tasks.

Notifications

The daemon watches each PTY session's terminal title to detect working and idle transitions. It stores the current working state in the authoritative session metadata and shares updates with clients and cluster peers, which keeps terminal sidebar spinners in sync even when a client is not attached to that terminal's output. Idle transitions are also relayed to connected clients for an in-app desktop popup/sound. Notifications are local to the app; there are no remote push backends.

Updates

The desktop and mobile app and the daemon and CLI fetch updates over the air from a configured manifest URL. Updating a daemon always stages and installs the matching CLI as the same release unit. See Remote-URL Updates.

Concurrency model

The daemon is an async, multi-task service. At a high level:

• Sessions are held in an in-memory map with per-session locking, so attaching, reading, and writing different sessions do not contend.
• Each session has bounded broadcast channels that fan output out to all attached clients; a slow client is shed rather than allowed to stall the others.
• Database writes are serialized and offloaded to a blocking thread pool so they never block the async runtime.
• In cluster mode, replicated state is versioned and snapshot-able, and the set of connected peers is dynamic.

Security

• Client auth: Token-based, constant-time comparison (timing-attack resistant)
• Peer auth: a shared cluster token in the peer handshake - rejected if mismatch
• Transport: Plain WebSocket (WS) for peer traffic; optional TLS (wss://) for client-facing daemon connections.
• Token generation: 32 random bytes, hex-encoded (256-bit entropy)