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 owns any session it creates: it serves the write locally and gossips the session metadata to all peers. Requests that must reach a live process (input, resize, output subscription) are forwarded to the owning node; everything else is served locally.

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 when an interactive agent CLI goes idle, and relays that 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. 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)