Installation

Prerequisites

Go 1.21+

Install Go

Git

Required — Hyve uses system git for all repository operations

Note

Cloud provider CLI: Hyve does not bundle cloud SDKs. Install the CLI for each provider you plan to use (AWS CLI, gcloud, az, civo CLI) and authenticate before running Hyve. See Quick Start for per-provider setup.

Note

Git Requirement: Hyve uses your system’s git binary for all repository operations. Git must be installed and available in your PATH before using any hyve git commands.

Install

Install with Go

go install github.com/cbridges1/hyve@latest

This installs the hyve binary to your $GOPATH/bin directory (usually ~/go/bin).

Ensure Go bin is in PATH

export PATH=$PATH:$(go env GOPATH)/bin

Add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.

Verify installation

hyve --help

You should see the Hyve help output listing all available commands.

Git Requirement

Hyve delegates all git operations to the system git binary.

# Verify git is installed
git --version

If git is not installed, download it from git-scm.com or install via your package manager:

# macOS
brew install git

# Ubuntu / Debian
sudo apt install git

# Windows
winget install Git.Git

Cloud Provider Setup

Hyve uses each provider’s native authentication. No credentials are stored in Hyve — your cloud CLI or environment variables are the sole credential source.

Civo

# Authenticate with the Civo CLI (writes ~/.civo.json)
civo apikey save my-token YOUR_CIVO_TOKEN
civo apikey use my-token

# Or via environment variable
export CIVO_TOKEN=your_civo_api_token

The Civo module reads the active token from ~/.civo.json or CIVO_TOKEN automatically.

AWS

# AWS CLI (recommended for local dev)
aws configure

# Or via environment variables
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1

The EKS module uses the standard AWS credential chain.

GCP

# Application Default Credentials (recommended for local dev)
gcloud auth application-default login

# Or via service account
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

Azure

# Azure CLI (recommended for local dev)
az login

# Or via service principal
export AZURE_TENANT_ID=your_tenant_id
export AZURE_CLIENT_ID=your_client_id
export AZURE_CLIENT_SECRET=your_client_secret

Directory Structure

After installation, Hyve creates:

~/.hyve/
├── repositories.db     # Repository configurations
├── temp/               # Temporary kubeconfig files
└── repositories/       # Cloned repository storage
    ├── production/
    │   ├── clusters/
    │   ├── workflows/
    │   ├── templates/
    │   └── hyve.lock
    └── development/

Overriding the data directory

The default ~/.hyve location can be overridden with the --home flag or the HYVE_HOME environment variable:

# Use a custom directory for a single command
hyve --home /tmp/hyve-staging reconcile

# Set it persistently for a shell session
export HYVE_HOME=~/hyve-staging
hyve git add staging --repo-url https://github.com/company/staging-state.git

# Or point to an existing directory
HYVE_HOME=/opt/hyve hyve cluster list

The --home flag takes precedence over HYVE_HOME.

Platform-Specific Notes

macOS

On macOS, you may need to allow the binary in Security & Privacy settings:

1. Run hyve once
2. Go to System Settings → Privacy & Security
3. Click “Allow Anyway” for the hyve binary

Linux

Ensure you have the necessary dependencies:

# Debian/Ubuntu
sudo apt-get install git

# RHEL/CentOS
sudo yum install git

Windows

Variable substitution in workflows uses cmd /C "command". Use %VAR% for environment variables alongside ${VAR} for workflow variables.

To persist environment variables across sessions, set them via System Properties or add them to your PowerShell profile.

Verifying Installation

Run these commands to verify everything is set up correctly:

# Check Hyve installation
hyve --help

# Verify system git is available
git --version

# List configured git repositories (after adding one)
hyve git list

Troubleshooting

Command not found

Ensure the hyve binary is in your PATH:

# Check if hyve is in PATH
which hyve

# If not, add Go bin to PATH
export PATH=$PATH:$(go env GOPATH)/bin

Permission denied

Make the binary executable:

chmod +x $(which hyve)

Go binary not found after install

Ensure $(go env GOPATH)/bin is in your PATH. Add to your shell profile:

echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.zshrc
source ~/.zshrc

Next Steps

Quick Start

Create your first cluster

Module System

Learn how modules work

CLI Reference

Explore all commands

Git Management

Set up repositories