hivekit 0.1.0

Toolkits for using hive agents, including CLI and SDK.

       ███          █████   █████  ███                       █████   ████  ███   █████
      ░░░███       ░░███   ░░███  ░░░                       ░░███   ███░  ░░░   ░░███
        ░░░███      ░███    ░███  ████  █████ █████  ██████  ░███  ███    ████  ███████
          ░░░███    ░███████████ ░░███ ░░███ ░░███  ███░░███ ░███████    ░░███ ░░░███░
           ███░     ░███░░░░░███  ░███  ░███  ░███ ░███████  ░███░░███    ░███   ░███
         ███░       ░███    ░███  ░███  ░░███ ███  ░███░░░   ░███ ░░███   ░███   ░███ ███
       ███░         █████   █████ █████  ░░█████   ░░██████  █████ ░░████ █████  ░░█████
      ░░░          ░░░░░   ░░░░░ ░░░░░    ░░░░░     ░░░░░░  ░░░░░   ░░░░ ░░░░░    ░░░░░

> HiveKit

Command-line interface for managing Hive AI agent experiments

Installation • Quick Start • Commands • Configuration

Installation

pip install hivekit

Requirements: Python 3.12+

From source:

git clone https://github.com/hiverge/hivekit.git
cd hivekit
source start.sh

Quick Start

1. Initialize and authenticate:

# Initialize config with your organization ID
hive init

# Authenticate with Hive platform
hive login

2. Create your experiment configuration file:

Create a hive.yaml file in your project directory:

version: v1alpha1
experiment_name: my-experiment-  # '-' suffix generates unique ID

repo:
  source: https://github.com/your-org/your-repo.git
  branch: main
  evaluation_script: evaluation.py
  target_code:
    - main.py

runtime:
  num_agents: 1
  max_runtime_seconds: -1  # -1 = unlimited
  max_iterations: -1       # -1 = unlimited

sandbox:
  base_image: python:3.9-slim
  setup_script: |
    pip install -r requirements.txt
  evaluation_timeout: 60
  resources:
    cpu: "2"
    memory: 4Gi

3. Create and manage experiments:

# Create an experiment from config file
hive create exp -f hive.yaml

# Create with overrides
hive create exp -f hive.yaml repo.branch=dev sandbox.resources.cpu=1

# List all experiments
hive list exp

# Get experiment details
hive get exp my-experiment-abc123

# Delete experiment
hive delete exp my-experiment-abc123

Commands Reference

Setup & Authentication

hive init                    # Initialize configuration with organization ID
hive login                   # Authenticate with Hive platform
hive logout                  # Clear stored credentials

Experiment Management

hive create exp -f <config>             # Create experiment from config file
hive create exp -f <config> key=value   # Create with config overrides
hive list exp                           # List all experiments
hive get exp <name>                     # Get detailed experiment information
hive delete exp <name>                  # Delete single experiment

Batch Operations

# Delete multiple experiments
hive delete exp exp-1 exp-2 exp-3

# Skip confirmation with -y flag
hive delete exp exp-1 exp-2 exp-3 -y

Example output:

experiment "exp-1" deleted
experiment "exp-2" deleted
experiment "exp-3" deleted
Total: 3 deleted

Help

hive --help                  # Show all commands
hive <command> --help        # Show help for specific command

Configuration Guide

Config File Locations

• User config: ~/.hive/config.yaml - stores organization_id (created by hive init)
• Experiment config: hive.yaml in your project - required for creating experiments

Creating Experiments with Config Overrides

You can override any config value when creating an experiment:

# Override single values
hive create exp -f hive.yaml repo.branch=feature/new-feature

# Override multiple values
hive create exp -f hive.yaml \
  repo.branch=dev \
  sandbox.resources.cpu=1 \
  runtime.num_agents=5

# Override experiment name
hive create exp -f hive.yaml experiment_name=test-run-

Configuration Sections

Experiment Name

experiment_name: my-experiment-  # '-' suffix generates unique hash

Add a - suffix to auto-generate a unique ID (e.g., my-experiment-abc123).

Repository (repo)

Defines the code repository for your experiments:

repo:
  source: https://github.com/your-org/repo.git   # Git repository URL
  branch: main                                    # Branch to use
  evaluation_script: evaluation.py                # Script that evaluates results
  target_code:                                    # YAML list of files (required)
    - main.py
    - utils.py
    - file.py:1-10                                # Optional: specify line ranges
  github_token_variable: GITHUB_TOKEN             # Optional: env var for PAT

Private repositories: Use github_token_variable to reference an environment variable containing your GitHub Personal Access Token:

export GITHUB_TOKEN=ghp_your_token_here
hive create exp -f hive.yaml

Runtime (runtime)

Controls experiment execution:

runtime:
  num_agents: 10              # Number of parallel agents
  max_runtime_seconds: 3600   # Max execution time (-1 = unlimited)
  max_iterations: 100         # Max iterations per agent (-1 = unlimited)

Sandbox (sandbox)

Defines the execution environment:

sandbox:
  base_image: python:3.9-slim  # Docker base image
  setup_script: |              # Required: commands to run on startup
    pip install -r requirements.txt
  evaluation_timeout: 60       # Max time for evaluation script in seconds
  resources:
    cpu: "2"                   # CPU request/limit
    memory: 4Gi                # Memory limit

Environment Variables

• EDITOR - Text editor for hive edit config (default: vim)

Understanding Experiments

Experiment Lifecycle

1. Pending - Experiment submitted, waiting to start
2. ImageBuilding - Building container images
3. InProgress - Agents are being initialized
4. Running - Agents are executing experiments
5. Completed - All agents finished successfully

List Output

NAME                  AGENTS  STATUS          AGE
my-experiment-abc123  10/10  Running         5m
test-exp-xyz789       0/10   ImageBuilding   2h
debug-exp-abc789      5/10   InProgress      15m

• AGENTS: Shows ready/total (e.g., 8/10 = 8 agents ready out of 10)
• STATUS: Current experiment phase (Pending → ImageBuilding → InProgress → Running → Completed)
• AGE: Time since creation

Get Experiment Details

$ hive get exp my-experiment-abc123

apiversion: v1alpha1
name: my-experiment-abc123
spec
  repo
    source:             https://github.com/your-org/repo.git
    branch:             main
    evaluation_script:  evaluation.py
    target_code:
      - main.py
      - utils.py
  runtime
    agents:          10/10
    max_runtime:     -1
    max_iterations:  -1
  sandbox
    base_image:          python:3.9-slim
    evaluation_timeout:  60s
    setup_script:
      pip install -r requirements.txt
    resources:
      cpu:    2
      memory: 4Gi
status
  created: 2026-04-22T10:30:00Z (2h ago)
  phase:   Running
  message: Experiment is running successfully

Output sections:

• name: Experiment identifier (auto-generated if name ended with -)
• spec: Experiment specification
  • repo: Source code repository configuration
    • target_code: Files for agents to focus on (can be single file or list)
  • runtime: Execution settings (agents shows ready/total, e.g., 10/10)
  • sandbox: Container environment and resources
• status: Current state
  • created: Creation timestamp and age
  • phase: Current lifecycle phase
  • message: Condition message (if available)

Development

Setup:

git clone https://github.com/hiverge/hivekit.git
cd hivekit
source start.sh

Testing:

uv pip install -e ".[test]"
make test

Linting:

uv pip install -e ".[lint]"
make lint

Support

• 📖 Documentation
• 🐛 Issues

License

MIT License - see LICENSE