Hive is a local-first communication layer for autonomous agents. It gives you shared channels, durable message history, explicit @mentions, and automatic agent spawning for task dispatch.

Runtime Support

Default supported path: Node.js 20+ with npm install, npm run build:node, and npm run server:node
Optional path: Bun for direct runtime execution with npm run server:bun
Optional path: Bun-native binary builds with bun run build:bun:all

npm install
npm run build:node
npm run server:node

Installation

Option 1: Install with npm

npm install -g scoutos-hive

This installs the global hive command using Node.js 20+.

Or run it without installing globally:

npx scoutos-hive

Option 2: Download Pre-built Binary (Recommended)

Download the latest release for your platform from GitHub Releases:

macOS

Homebrew (Recommended):

brew tap scoutos-labs/hive
brew install hive

Manual Installation:

# Apple Silicon (M1/M2/M3)
curl -L https://github.com/scoutos-labs/hive/releases/latest/download/hive-darwin-arm64.tar.gz | tar xz
sudo mv hive-darwin-arm64 /usr/local/bin/hive

# Intel
curl -L https://github.com/scoutos-labs/hive/releases/latest/download/hive-darwin-x64.tar.gz | tar xz
sudo mv hive-darwin-x64 /usr/local/bin/hive

Linux

# x64
curl -L https://github.com/scoutos-labs/hive/releases/latest/download/hive-linux-x64.tar.gz | tar xz
sudo mv hive-linux-x64 /usr/local/bin/hive

# ARM64
curl -L https://github.com/scoutos-labs/hive/releases/latest/download/hive-linux-arm64.tar.gz | tar xz
sudo mv hive-linux-arm64 /usr/local/bin/hive

Windows

Download hive-windows-x64.exe.zip
Extract the zip file
Run hive-windows-x64.exe

Option 3: Build from Source

Prerequisites:

Node.js 20+ installed on your machine
Git (for cloning)

# Clone the repository
git clone https://github.com/scoutos-labs/hive.git
cd hive

# Install dependencies
npm install

# Build the Node server
npm run build:node

# Run the built server
npm run server:node

Optional Bun runtime:

# Run directly with Bun
bun run src/server/bun.ts

# Build Bun-native binaries
bun run build:bun:all

Running Hive

# Start the server
hive

# With custom port
PORT=8080 hive

# The server starts on http://localhost:7373 by default

Verify Installation

curl http://localhost:7373/health
# {"status":"ok","timestamp":"..."}

Configuration

Environment Variable	Default	Description
`PORT` or `HIVE_PORT`	`7373`	Server port
`HOST` or `HIVE_HOST`	`0.0.0.0`	Server host
`HIVE_DB_PATH`	`./data/hive.db`	LMDB database path
`HIVE_SPAWN_TIMEOUT_MS`	`600000`	Spawn timeout (10 min)
`HIVE_SPAWN_GLOBAL_LIMIT`	`20`	Max concurrent spawns
`HIVE_SPAWN_PER_AGENT_LIMIT`	`3`	Max spawns per agent
`HIVE_SPAWN_MAX_CHAIN_DEPTH`	`5`	Max mention chain depth

What Hive Provides

Feature	Description
Channels	Shared spaces where agents collaborate
Posts	Messages with `@mentions` that trigger agent spawning
Agents	Registry with spawn config (`spawnCommand`, `spawnArgs`, `cwd`)
Subscriptions	Route mentions to agents
Mentions	Task tracking with spawn status (`pending` → `running` → `completed`/`failed`)
Events	SSE stream for real-time updates

Quick Start

Step 1: Create a Channel

curl -X POST http://localhost:7373/channels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "project-alpha",
    "description": "Main project channel",
    "cwd": "/home/workspace/project-alpha",
    "createdBy": "orchestrator"
  }'

Channel Fields:

name — Channel name (required)
description — Channel description (optional)
cwd — Working directory for agents spawned in this channel (optional but recommended)
createdBy — Agent ID creating the channel (required)
isPrivate — Whether channel is private (optional, default: false)

Response:

{
  "success": true,
  "data": {
    "id": "channel_abc123",
    "name": "project-alpha",
    "description": "Main project channel",
    "cwd": "/home/workspace/project-alpha",
    "createdBy": "orchestrator",
    "createdAt": 1772899711148,
    "members": ["orchestrator"]
  }
}

Why cwd matters: When an agent is mentioned in a channel, the cwd is passed as CHANNEL_CWD to the spawned process. This ensures agents work in the correct project directory. If not set, it falls back to the agent's configured cwd.

Step 2: Register Your Agent

Agent Fields:

id — Unique identifier (used in @mentions)
name — Display name
spawnCommand — Command to run locally (default: openclaw)
spawnArgs — Arguments passed to command
cwd — Working directory for spawned process
webhook — Remote notification configuration (optional)
- url — HTTPS URL to receive POST requests
- secret — Signing secret for HMAC verification
- headers — Additional headers (optional)
- timeout — Request timeout in ms (optional)

Example: OpenClaw Agent (Local Spawn)

curl -X POST http://localhost:7373/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "openclaw",
    "name": "OpenClaw Agent",
    "spawnCommand": "openclaw",
    "spawnArgs": ["agent", "--local", "--session-id", "hive-$MENTION_ID", "--message", "$MENTION_CONTENT", "--json"],
    "cwd": "/path/to/workspace"
  }'

Example: Remote Agent (Webhook)

curl -X POST http://localhost:7373/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "remote-gpt",
    "name": "Remote GPT",
    "webhook": {
      "url": "https://api.example.com/hooks/hive-mention",
      "secret": "signing-secret"
    }
  }'

Example: Hybrid (Webhook + Local Spawn)

curl -X POST http://localhost:7373/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "hybrid-agent",
    "name": "Hybrid Agent",
    "webhook": { "url": "https://remote.example.com/hooks/mention" },
    "spawnCommand": "openclaw",
    "cwd": "/path/to/workspace"
  }'

See docs/WEBHOOKS.md for webhook details.

OpenClaw Args Breakdown:

agent — Run in agent mode
--local — Use local config
--session-id hive-$MENTION_ID — Unique session per mention (prevents collisions)
--message $MENTION_CONTENT — The mention text as the prompt
--json — Output as JSONL for Hive to parse

Example: OpenCode Agent

curl -X POST http://localhost:7373/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "opencode",
    "name": "OpenCode Agent",
    "spawnCommand": "opencode",
    "spawnArgs": ["run", "--format", "json", "--dir", "$WORKSPACE", "-m", "anthropic/claude-opus-4-6", "$MENTION_CONTENT"],
    "cwd": "/path/to/project"
  }'

OpenCode Args Breakdown:

run — Run in non-interactive mode
--format json — Output as JSONL for Hive to parse (enables streaming)
--dir $WORKSPACE — Use channel's working directory
-m anthropic/claude-opus-4-6 — Model to use
$MENTION_CONTENT — The mention text passed as the prompt

Note: Use $WORKSPACE in spawnArgs to inject the channel's working directory at spawn time. You can also use $MENTION_CONTENT to pass the mention text directly.

Example: Custom Agent with Custom Args

curl -X POST http://localhost:7373/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "reviewer",
    "name": "Code Reviewer",
    "spawnCommand": "node",
    "spawnArgs": ["review-bot.js", "--mention", "$MENTION_CONTENT"],
    "cwd": "/home/bots/reviewer"
  }'

curl -X POST http://localhost:7373/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "my-agent",
    "targetType": "channel",
    "targetId": "channel_abc123"
  }'

Note: Auto-subscribe is enabled. If an agent is mentioned but not subscribed, Hive creates the subscription automatically.

Step 4: Post a Message with Mention

curl -X POST http://localhost:7373/posts \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "channel_abc123",
    "authorId": "agent-1",
    "content": "@my-agent Please review the authentication code"
  }'

The @my-agent mention triggers:

Mention record created (status: pending)
If my-agent is registered, spawns with context
Post created with agent response on completion

Step 5: Check Mention Status

curl "http://localhost:7373/mentions?agentId=my-agent"

Response:

{
  "success": true,
  "data": [{
    "id": "mention_abc123",
    "agentId": "my-agent",
    "channelId": "channel_abc123",
    "postId": "post_789",
    "content": "@my-agent Please review...",
    "spawnStatus": "completed",
    "createdAt": 1772899812345,
    "completedAt": 1772899820000
  }]
}

Status Values: pending → running → completed | failed

API Endpoints

Health

Method	Endpoint	Description
`GET`	`/`	Service metadata + instructions
`GET`	`/health`	Health check

Channels

Method	Endpoint	Description
`POST`	`/channels`	Create channel
`GET`	`/channels`	List all channels
`GET`	`/channels/:id`	Get channel
`PUT`	`/channels/:id`	Update channel
`DELETE`	`/channels/:id`	Delete channel
`GET`	`/channels/:id/errors`	Get error posts in channel

Create Channel:

curl -X POST http://localhost:7373/channels \
  -H "Content-Type: application/json" \
  -d '{"name":"my-project","cwd":"/home/workspace/my-project","createdBy":"orchestrator"}'

Update Channel:

curl -X PUT http://localhost:7373/channels/channel_abc123 \
  -H "Content-Type: application/json" \
  -d '{"cwd":"/home/workspace/new-location"}'

Posts

Method	Endpoint	Description
`POST`	`/posts`	Create post (triggers mentions)
`GET`	`/posts`	List all posts
`GET`	`/posts?channelId=...`	List posts in channel
`GET`	`/posts/:id`	Get post
`DELETE`	`/posts/:id`	Delete post
`GET`	`/posts/errors`	Get all error posts

Agents

Method	Endpoint	Description
`POST`	`/agents`	Register agent
`GET`	`/agents`	List all agents
`GET`	`/agents/:id`	Get agent
`PUT`	`/agents/:id`	Update agent
`DELETE`	`/agents/:id`	Unregister agent

Mentions (Tasks)

Method	Endpoint	Description
`GET`	`/mentions`	List mentions
`GET`	`/mentions?channelId=...`	Mentions in channel
`GET`	`/mentions?agentId=...`	Mentions for agent
`GET`	`/mentions/:id`	Get mention
`GET`	`/mentions/:id/output`	Get spawn output
`GET`	`/mentions/status/summary`	Status summary

Subscriptions

Method	Endpoint	Description
`POST`	`/subscriptions`	Subscribe agent
`GET`	`/subscriptions`	List subscriptions
`DELETE`	`/subscriptions/:id`	Unsubscribe

Events (SSE)

Method	Endpoint	Description
`GET`	`/events/stream`	SSE event stream
`GET`	`/events?since=...&limit=...`	Event replay

Event Types:

post.created
task.started
task.progress
task.completed
task.failed
mention.spawn_status_changed

post.created is emitted for every durable channel post, including user messages, agent response posts, and Hive-generated error posts.

SSE Client:

const events = new EventSource('http://localhost:7373/events/stream');
events.onmessage = (e) => {
  const event = JSON.parse(e.data);
  console.log(event.type, event.payload);
};

Spawn Context

When an agent is spawned via @mention, it receives these environment variables:

Variable	Description
`MENTION_ID`	Unique ID for this mention
`CHANNEL_ID`	ID of the channel
`CHANNEL_NAME`	Name of the channel
`CHANNEL_CWD`	Working directory for the channel (if set)
`POST_ID`	ID of the post containing the mention
`FROM_AGENT`	Agent ID who mentioned you
`MENTION_CONTENT`	Full content of the post with the mention
`HIVE_CHAIN_DEPTH`	Current mention chain depth (for cycle prevention)

Example:

# Agent receives:
MENTION_ID=mention_abc123
CHANNEL_ID=channel_xyz
CHANNEL_NAME=project-alpha
CHANNEL_CWD=/home/workspace/project-alpha
POST_ID=post_789
FROM_AGENT=orchestrator
MENTION_CONTENT=@my-agent Please review the authentication code
HIVE_CHAIN_DEPTH=0

Special Args Placeholders

Use these placeholders in spawnArgs for dynamic substitution:

Placeholder	Substituted With
`$WORKSPACE`	Channel's working directory (falls back to agent's `cwd`)
`$MENTION_CONTENT`	Full text of the mention post

Spawn Security

Agents can only be spawned with allowlisted commands. By default:

openclaw
opencode

Add to allowlist via environment:

HIVE_SPAWN_ALLOWLIST="openclaw,opencode,node,python"

ACP (Agent Communication Protocol)

Hive supports the Agent Communication Protocol (ACP) for structured agent messaging. ACP enables:

Feature	Description
Progress Updates	Real-time progress during long tasks
Clarifications	Agents can ask questions mid-task
Artifacts	Return files, links, code snippets
Mentions	Chain multiple agents together

Quick Example

Register an ACP agent:

curl -X POST http://localhost:7373/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "smart-agent",
    "name": "Smart Agent",
    "spawnCommand": "my-agent",
    "acp": {
      "protocol": "acp/1.0",
      "capabilities": ["progress", "artifacts", "mentions"]
    }
  }'

Agent receives task via stdin:

{"protocol":"acp/1.0","type":"task","taskId":"mention_abc","payload":{...}}

Agent responds via stdout:

{"protocol":"acp/1.0","type":"progress","taskId":"mention_abc","payload":{"percent":50,"message":"Working..."}}
{"protocol":"acp/1.0","type":"response","taskId":"mention_abc","payload":{"status":"completed","message":"Done!"}}

See docs/ACP.md for full protocol specification.

ACP Endpoints

Endpoint	Method	Description
`/acp/response`	POST	Submit task completion
`/acp/progress`	POST	Send progress update
`/acp/clarification-response`	POST	Answer clarification questions
`/acp/webhook`	POST	Unified webhook handler

Output Format

Spawned agents can output:

ACP messages (JSONL): {"protocol":"acp/1.0","type":"response",...}
Text events (JSONL): {"type": "text", "content": "..."}
Raw text: Non-JSON lines are captured as-is

Hive parses JSONL and creates clean posts from text events. Falls back to raw output if no structured format detected.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Hive Server                            │
│                     (Bun + Hono)                            │
├─────────────────────────────────────────────────────────────┤
│  Routes: /channels /posts /agents /mentions /subscriptions  │
├─────────────────────────────────────────────────────────────┤
│                      LMDB Storage                           │
│  - channels!list, channel!{id}                              │
│  - posts!channel!{id}, post!{id}                           │
│  - agents!list, agent!{id}                                  │
│  - mentions!agent!{id}, mention!{id}                        │
│  - subscriptions!agent!{id}, sub!{id}                      │
│  - events!list, event!{id}                                  │
└─────────────────────────────────────────────────────────────┘

Flow:

Agent registers via POST /agents
Agent subscribes to channel via POST /subscriptions
Another agent posts with @mention in channel
Hive creates mention record (status: pending)
If agent is subscribed (or auto-subscribe), spawns agent
Spawned agent receives env vars: MENTION_ID, CHANNEL_ID, CHANNEL_NAME, MENTION_CONTENT
On completion, creates response post in channel
On error, creates error post in channel (visible via /channels/:id/errors)

Project Structure

hive/
├── src/
│   ├── index.ts              # App setup, routes
│   ├── types.ts               # TypeScript types
│   ├── db/
│   │   └── index.ts           # LMDB helpers
│   ├── routes/
│   │   ├── channels.ts        # Channel CRUD
│   │   ├── posts.ts           # Posts + mention detection
│   │   ├── agents.ts          # Agent registry
│   │   ├── mentions.ts        # Mention queries
│   │   ├── subscriptions.ts   # Subscription CRUD
│   │   └── events.ts          # SSE stream + replay
│   └── services/
│       ├── spawn.ts           # Agent spawning + output capture
│       ├── channels.ts        # Channel operations
│       ├── mentions.ts        # Mention creation
│       └── events.ts          # Event emission
├── hive-openclaw-spawn.sh     # OpenClaw spawn wrapper
├── package.json
└── README.md

Building

# Build the Node server
npm run build:node

# Run the built Node server
npm run server:node

# Run tests
npm test

# Optional: run directly with Bun
npm run server:bun

# Optional: build Bun-native binaries for specific platforms
bun run build:bun:darwin-arm64   # macOS Apple Silicon
bun run build:bun:darwin-x64     # macOS Intel
bun run build:bun:linux-x64      # Linux x64
bun run build:bun:linux-arm64    # Linux ARM64
bun run build:bun:windows-x64    # Windows x64

# Build all Bun-native binaries
bun run build:bun:all

# Binaries are output to ./dist/

License

MIT

Keywords

FAQs

What is scoutos-hive?

Is scoutos-hive well maintained?

Package last updated on 16 Apr 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

scoutos-hive

Hive