This guide installs Hive on a single server using the binary installer. For multi-server clusters, see Multi-Node Installation. To build from source, see Source Install.

Supported Operating Systems:

Ubuntu 22.04 / 24.04 / 25.10
Debian 12.13

What gets installed:

Hive daemon and CLI
QEMU/KVM for virtual machine management
OVN/Open vSwitch for VPC networking
Predastore (S3-compatible object storage)
Viperblock (EBS-compatible block storage)
AWS CLI v2

Instructions

Step 1. Install Hive

curl https://install.mulgadc.com/ | bash

The installer downloads the Hive binary and bootstraps all dependencies (QEMU, OVN/OVS, AWS CLI).

Step 2. Initialize a region

Create your first region and availability zone:

hive admin init --region ap-southeast-2 --az ap-southeast-2a --node node1 --nodes 1

Step 3. Trust the CA certificate

Hive generates a local CA during initialization. Add it to your system trust store:

sudo cp ~/hive/config/ca.pem /usr/local/share/ca-certificates/hive-ca.crt
sudo update-ca-certificates

Step 4. Start services

hive start

Set the AWS profile to use the default admin account:

export AWS_PROFILE=hive

Step 5. Import an AMI

List available images and import one matching your architecture:

hive admin images list
hive admin images import --name debian-12-arm64

Step 6. Create a VPC and launch an instance

aws ec2 create-vpc --cidr-block 10.200.0.0/16
export HIVE_VPC="vpc-XXX"

aws ec2 create-subnet --vpc-id $HIVE_VPC --cidr-block 10.200.1.0/24
export HIVE_SUBNET="subnet-XXX"

aws ec2 import-key-pair --key-name "hive-key" --public-key-material fileb://~/.ssh/id_rsa.pub

aws ec2 run-instances \
  --image-id $HIVE_AMI \
  --instance-type t3.small \
  --key-name hive-key \
  --subnet-id $HIVE_SUBNET \
  --count 1

Step 7. Connect via SSH

Find the forwarded SSH port and connect:

ps auxw | grep hostfwd
# Look for: hostfwd=tcp:127.0.0.1:<port>-:22

ssh -i ~/.ssh/hive-key ec2-user@127.0.0.1 -p <port>

Troubleshooting

hive command not found

The binary is not in your PATH. Run the installer again or add the install directory to your PATH:

export PATH=$PATH:~/hive/bin/

Add this to your ~/.bashrc or ~/.zshrc for persistence.

OVN services not starting

Check if the OVN controller is active:

sudo systemctl is-active ovn-controller
sudo ovn-sbctl show

If inactive, re-run the OVN setup that the installer performs. Check system logs for details:

journalctl -u ovn-controller --no-pager -n 20

CA certificate not trusted

AWS CLI will reject HTTPS connections if the Hive CA is not trusted. Re-add the certificate:

sudo cp ~/hive/config/ca.pem /usr/local/share/ca-certificates/hive-ca.crt
sudo update-ca-certificates

Verify it was added:

ls -la /usr/local/share/ca-certificates/hive-ca.crt

Instance stuck in pending

Check the Hive daemon logs for errors:

ls ~/hive/logs/
cat ~/hive/logs/daemon.log

Verify the AMI was imported successfully:

aws ec2 describe-images

SSH connection refused

cloud-init takes 30-60 seconds to configure the instance after boot. Wait and retry.

Verify the SSH port forwarding is active:

ps auxw | grep hostfwd

If no hostfwd entry appears, the instance may not have started correctly. Check instance state:

aws ec2 describe-instances --instance-ids $INSTANCE_ID

README.md

Installing Hive

Table of Contents

Overview