Quickstart

Prerequisites

Before you begin, ensure you have:

Python 3.11+ for agent development
An LLM provider (Anthropic, OpenAI, Google Gemini, or local models via Ollama)
Git for cloning the repository

Windows Users: Use WSL (Windows Subsystem for Linux) or Git Bash. Some core automation scripts may not execute correctly in standard Command Prompt or PowerShell.

Installation

Hive uses a uv workspace layout and is not installed with pip install. Running pip install -e . from the repository root will create a placeholder package and Hive will not function correctly.

Clone the repository

git clone https://github.com/aden-hive/hive.git
cd hive

Run the quickstart script

./quickstart.sh

This automated script sets up:

Framework - Core agent runtime and graph executor (in core/.venv)
Aden Tools - 100+ MCP tools for agent capabilities (in tools/.venv)
Credential store - Encrypted API key storage (~/.hive/credentials)
LLM provider - Interactive default model configuration
All required Python dependencies with uv

Configure your LLM provider

The quickstart script will prompt you to configure your LLM provider. Enter your API key when prompted:

? Select your LLM provider:
  > Anthropic (Claude)
    OpenAI (GPT-4)
    Google (Gemini)
    Local (Ollama)

Your credentials are stored securely in ~/.hive/credentials with encryption.

Launch the dashboard

The script will automatically open the Hive dashboard in your browser at http://localhost:3000.

Build your first agent

There are three ways to create agents in Hive:

Browser Dashboard
Command Line (TUI)
Code-First

Using the Web Interface

Describe your agent: Type what you want your agent to do in the input box on the home screen.
The Queen Bee coding agent will generate the agent graph, nodes, and connection code automatically.
Review and approve the generated agent structure.
Run your agent by clicking the Run button or asking the Queen Bee to execute it.

Click “Try a sample agent” to explore pre-built templates. You can run them directly or customize them for your needs.

Using the Terminal UI

./hive tui

The TUI provides:

Agent browser - View all your agents
Real-time execution - Watch agents run with live updates
Session management - Resume paused sessions
Log viewer - Debug with full execution logs

Navigate with arrow keys, press Enter to select, and q to quit.

Programmatic Agent Creation

Create an agent by defining its graph structure in Python:

from framework import Agent, Goal, SuccessCriterion
from framework.graph import Node, Edge

# Define your goal
goal = Goal(
    id="research-report",
    name="Research Report Generator",
    success_criteria=[
        SuccessCriterion(
            id="comprehensive",
            description="Report covers all major aspects",
            metric="llm_judge",
            weight=0.5
        )
    ]
)

# Create nodes
research_node = Node(
    id="research",
    type="event_loop",
    system_prompt="Research the topic thoroughly",
    tools=["web_search", "web_scrape"],
    outputs=["research_data"]
)

write_node = Node(
    id="write",
    type="event_loop",
    system_prompt="Write a comprehensive report",
    inputs=["research_data"],
    outputs=["report"]
)

# Define the agent
agent = Agent(
    goal=goal,
    nodes=[research_node, write_node],
    edges=[
        Edge(source="research", target="write", condition="ON_SUCCESS")
    ]
)

# Run the agent
result = agent.run({"topic": "AI agent frameworks"})
print(result["report"])

Save this as my_agent.py and run:

./hive run my_agent.py --input '{"topic": "AI agent frameworks"}'

Use template agents

Hive includes several pre-built agent templates:

Deep Research Agent

Comprehensive research with multiple sources, synthesis, and citation

Email Inbox Manager

Automated email triage, categorization, and response drafting

Job Application Hunter

Search job boards, analyze postings, and generate tailored applications

Tech News Reporter

Monitor tech news, summarize developments, and create digests

To use a template:

Click “Try a sample agent” in the dashboard
Browse available templates
Select a template and click Run to execute it as-is
Or click Customize to modify it for your needs

Run agents via CLI

Once an agent is created, you can run it from the command line:

# Run an agent
./hive run <agent-name> --input '{"key": "value"}'

# Run in interactive shell mode
./hive shell <agent-name>

# Show agent information
./hive info <agent-name>

# List all agents
./hive list

Configuration

Your Hive installation creates several configuration files:

~/.hive/config.yaml - Global settings

llm:
  provider: anthropic
  model: claude-3-5-sonnet-20241022
  
credentials:
  storage: encrypted_file
  
logging:
  level: info
  runtime_logs: true

~/.hive/credentials - Encrypted credentials

# Auto-managed by the credential store
# Use: ./hive credentials add <name>
# View: ./hive credentials list

core/config.yaml - Framework configuration

runtime:
  max_iterations: 10
  checkpoint_interval: 5
  
monitoring:
  enable_health_check: true
  stream_events: true
  
cost_tracking:
  enable: true
  budget_per_session: 5.0  # USD

Troubleshooting

'uv' command not found

The quickstart script installs uv automatically. If you see this error:

# Install uv manually
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

# Verify installation
uv --version

Port 3000 already in use

If another service is using port 3000:

# Find the process
lsof -i :3000

# Kill it or change Hive's port
PORT=8080 ./hive tui

LLM API key errors

Verify your credentials:

# List stored credentials
./hive credentials list

# Test a credential
./hive credentials test anthropic_api_key

# Add or update
./hive credentials add anthropic_api_key

Python version issues

Hive requires Python 3.11+:

# Check your version
python --version

# If using pyenv
pyenv install 3.11
pyenv local 3.11

# Re-run quickstart
./quickstart.sh

Next steps

Learn key concepts

Understand goals, graphs, nodes, and self-improvement

Build an agent

Deep dive into creating custom agents

Explore tools

Discover 100+ built-in MCP tools

Deploy to production

Self-host Hive in your infrastructure

Get Started

Core Concepts

Building Agents

Runtime & Execution

Guides

Prerequisites

Installation

Build your first agent

Using the Web Interface

Using the Terminal UI

Programmatic Agent Creation

Use template agents

Deep Research Agent

Email Inbox Manager

Job Application Hunter

Tech News Reporter

Run agents via CLI

Configuration

Troubleshooting

Next steps

Learn key concepts

Build an agent

Explore tools

Deploy to production

Build docs developers (and LLMs) love

Get Started

Core Concepts

Building Agents

Runtime & Execution

Guides

​Prerequisites

​Installation

​Build your first agent

​Using the Web Interface

​Using the Terminal UI

​Programmatic Agent Creation

​Use template agents

Deep Research Agent

Email Inbox Manager

Job Application Hunter

Tech News Reporter

​Run agents via CLI

​Configuration

​Troubleshooting

​Next steps

Learn key concepts

Build an agent

Explore tools

Deploy to production

Build docs developers (and LLMs) love

Prerequisites

Installation

Build your first agent

Using the Web Interface

Using the Terminal UI

Programmatic Agent Creation

Use template agents

Run agents via CLI

Configuration

Troubleshooting

Next steps