Installation

Prerequisites

Go 1.26+

Install Go

Git

Needed to fetch modules from git repositories (hyve runs git clone). Your state directory doesn’t have to be a git repo — that’s up to you.

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.

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 (optional)

Hyve has no built-in git functionality — no clone, pull, push, or commit. hyve context create --path <dir> points hyve at any local directory directly; whether that directory is a git working tree is entirely up to you. If you do want it version-controlled, that’s your own git CLI, same as any other project:

git --version   # verify it's installed, if you're using it

See Contexts and Version Control for how this fits together.

Cloud Provider Setup

Hyve stores no cloud credentials of its own — each module reads whatever its provider’s own CLI or environment variables already provide, the same way you’d authenticate for that provider outside of Hyve entirely. For example, the Civo module reads the active token from ~/.civo.json (via civo apikey save/civo apikey use) or the CIVO_TOKEN environment variable.

Note

This is per-module, not something Hyve standardizes — an EKS module typically follows the AWS SDK’s default credential chain, a GKE module typically uses Application Default Credentials, and so on. Check the specific module’s own README for what it expects.

Directory Structure

After installation, Hyve creates:

~/.hyve/
├── hyve.db     # Registry of contexts (hyve context create/list/use)
└── temp/       # Temporary kubeconfig files

Context directories themselves live wherever you put them — Hyve never copies or clones anything into ~/.hyve; hyve.db just tracks where each registered context’s directory is. See Contexts.

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 context create staging --path ~/repos/staging-state

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

The --home flag takes precedence over HYVE_HOME.

Platform-Specific Notes

Linux

No system dependencies required for hyve itself. If you’re using a git-backed context directory (optional — see Git above):

# 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

# List registered contexts (after registering one)
hyve context 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

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