Configuration

Overview

Hyve’s configuration model is intentionally minimal. There are no embedded credential stores or cloud-provider config files. Everything lives in three places:

1. hyve.yaml at your repository root — reconciliation behaviour
2. hyve.lock at your repository root — locked module versions (auto-managed)
3. Your environment — credentials passed as module params or standard env vars

hyve.yaml

Place hyve.yaml at the root of your Hyve state repository to control reconciliation behaviour.

# hyve.yaml — placed at the root of your Hyve state repository
reconcile:
  mode: local                  # "local" (default) or "cicd"
  strictDelete: false          # set to true to warn about untracked cloud clusters
  strictResourceDelete: false  # set to true to auto-prune orphaned spec.resources entries

Field	Type	Default	Description
reconcile.mode	string	local	local — Hyve provisions clusters directly from the machine running hyve reconcile. cicd — Hyve validates and pushes desired state to Git; a CI/CD pipeline calls hyve reconcile --path . to provision.
reconcile.strictDelete	bool	false	When true, after each reconcile Hyve scans the cloud provider for clusters with no matching YAML in clusters/ and logs a warning naming each one — it does not delete anything automatically. See Provider Scan for what the scan can and can’t see.
reconcile.strictResourceDelete	bool	false	When true, a spec.resources entry removed from a cluster’s YAML without delete: true is pruned automatically instead of just logged as orphaned.

Note

If hyve.yaml is absent or a field is not set, Hyve uses the defaults shown above.

Caution

strictDelete and strictResourceDelete are not symmetric despite the similar name — strictResourceDelete auto-prunes; strictDelete only warns. A whole cluster is too large a blast radius to delete automatically off a provider scan that can itself have blind spots (see the linked section) — it surfaces the drift for a human to act on instead.

See the CI/CD Workflow Guide for a complete walkthrough of CI/CD mode with GitHub Actions.

server (optional)

Add a server block to configure hyve serve — hyve’s REST + WebSocket API mode:

server:
  port: 8080                            # default; also settable via --port or HYVE_PORT
  frontendUrl: "http://localhost:5173"  # opened by `hyve serve --open`

  auth:
    mode: none        # none (default) | forward
    forward:
      validateUrl: ""  # also settable via HYVE_AUTH_VALIDATE_URL
      timeout: "3s"    # also settable via HYVE_AUTH_VALIDATE_TIMEOUT

Field	Default	Description
server.port	8080	TCP port hyve serve listens on
server.frontendUrl	—	URL hyve serve --open navigates to
server.auth.mode	none	none — no auth. forward — every request’s Authorization header is forwarded to validateUrl for validation
server.auth.forward.validateUrl	—	External endpoint hyve delegates token validation to
server.auth.forward.timeout	3s	Timeout before the validator is treated as unreachable (fails closed)

See the Server Mode guide for the full REST API reference and authentication model.

env (optional)

Add an env block to point hyve at a local, gitignored file of environment variables — loaded before every reconcile and workflow run, CLI or server-triggered:

env:
  file: local.env   # relative to the repo root

Field	Default	Description
env.file	—	Path, relative to the repo root, to a .env-style file loaded into the process environment before reconciling or running a workflow. Unset means nothing extra is loaded.

Set it from the CLI or from Hyve Studio’s Configuration section — either way, the filename is automatically appended to .gitignore the moment it’s set, so it can’t ship to your remote by omission:

hyve config set env.file local.env
hyve config get

# local.env — never committed
CIVO_TOKEN=your-token
SOME_APP_SECRET=whatever

# clusters/my-cluster.yaml — reads from local.env, the real process
# environment, or CI secrets, in that order
spec:
  resources:
    - name: my-app
      source: ./resource-files/my-app.yaml
      values:
        token: ${SOME_APP_SECRET}

Note

Additive, not overriding: a variable already present in the real process environment (a CI secret, or something your shell already exported) always wins over env.file — the file only fills gaps. This is the same precedence hyve’s own bootstrap .env loading already uses, and matches workflow step env’s own inherited-environment-wins convention.

Caution

A configured path can’t point outside the repository — absolute paths and any path containing .. are rejected. env.file is for local convenience scoped to this repo, not a pointer to an arbitrary filesystem location.

See hyve config for the full CLI reference.

hyve.lock

hyve.lock is a content-addressed YAML lock file at the root of your state repository. It is auto-managed by the hyve module and hyve workflow commands and should be committed to Git.

version: 1
modules:
  github.com/hyve-modules/civo@v1.0.0:
    source: github.com/hyve-modules/civo@v1.0.0
    resolved: https://github.com/hyve-modules/civo/archive/v1.0.0.tar.gz
    sha256: "abc123..."
workflows:
  github.com/myorg/shared-workflows//setup-monitoring.yaml@v1.2.0:
    name: setup-monitoring
    source: github.com/myorg/shared-workflows//setup-monitoring.yaml@v1.2.0
    resolved: https://raw.githubusercontent.com/myorg/shared-workflows/v1.2.0/setup-monitoring.yaml
    sha256: "def456..."

The workflows key only appears once a template or cluster references a remote workflow — repositories using only local workflows in workflows/ don’t have it at all.

You should never edit hyve.lock directly. Use the module and workflow commands to manage it:

hyve module add github.com/hyve-modules/civo@v1.0.0    # add and lock a module
hyve module update github.com/hyve-modules/civo         # update a module to latest
hyve module install                                      # install all locked modules
hyve module list                                         # show locked modules

hyve workflow install                                    # lock all remote workflow refs
hyve workflow update github.com/myorg/shared-workflows//setup-monitoring.yaml
hyve workflow verify                                      # confirm cached content matches sha256

Credentials

Hyve does not store cloud credentials. Modules read credentials from:

1. Module params passed as --set KEY=VALUE when creating a template
2. Standard cloud CLI config files (~/.civo.json, ~/.aws/credentials, GCP ADC, az login session)
3. Environment variables (CIVO_TOKEN, AWS_ACCESS_KEY_ID, GOOGLE_APPLICATION_CREDENTIALS, etc.)

Passing credentials as params

When a module expects a credential (like a Civo API token), you can pass it directly as a template param. This value is stored in cluster.spec.params in the cluster YAML and injected as HYVE_PARAM_<KEY> on every reconcile.

hyve template create my-template \
  --driver github.com/hyve-modules/civo \
  --driver-version v1.0.0 \
  --region PHX1 \
  --set api_key=${CIVO_TOKEN}

Caution

Params stored in cluster.spec.params are committed to Git in plaintext. For sensitive values like API tokens, prefer environment variables over --set so the value is never written to the YAML file.

Environment variables

Most modules support reading credentials directly from the environment, matching their underlying cloud CLI conventions:

# Civo
export CIVO_TOKEN=your-token

# AWS
export AWS_ACCESS_KEY_ID=your-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1

# GCP
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# Azure
export AZURE_TENANT_ID=your-tenant-id
export AZURE_CLIENT_ID=your-client-id
export AZURE_CLIENT_SECRET=your-client-secret

For CI/CD pipelines, store credentials as pipeline secrets (e.g., GitHub Actions secrets) and export them before running hyve reconcile.

Git Credentials

For private Git repositories, configure authentication via environment variable or git’s credential helper:

# Environment variable (preferred for CI/CD)
export HYVE_GIT_TOKEN=ghp_xxxxxxxxxxxx

# Or configure git's credential manager
git config --global credential.helper osxkeychain  # macOS
git config --global credential.helper manager      # Windows

# SSH authentication
eval $(ssh-agent)
ssh-add ~/.ssh/id_rsa
hyve git add production --repo-url git@github.com:company/hyve-prod.git

See the Git Management guide for full authentication options.

Directory Structure

~/.hyve/
├── repositories.db     # Repository configurations (SQLite)
├── temp/               # Temporary kubeconfig files
└── repositories/       # Cloned repository storage
    └── <repo-name>/
        ├── clusters/       # Cluster YAML definitions
        ├── workflows/      # Workflow YAML definitions
        ├── templates/      # Template YAML definitions
        ├── hyve.yaml       # Reconciliation config (optional)
        └── hyve.lock       # Module + remote workflow lock file (auto-managed)

Configuration Priority

Hyve resolves values in this order:

Command-line flags

Highest priority — overrides all other sources

hyve cluster auth my-cluster

Environment variables

Second priority — from shell or CI/CD pipeline secrets

export CIVO_TOKEN=token

Cloud CLI credential stores

Third priority — ~/.civo.json, ~/.aws/credentials, GCP ADC, az login session

Default values

Lowest priority — built-in defaults from hyve.yaml or the module manifest

Security Best Practices

Use environment variables for secrets

Pass sensitive values like API tokens as environment variables rather than --set params. Environment variables are never written to Git.

export CIVO_TOKEN=your-token
# The module reads CIVO_TOKEN automatically — no --set needed
hyve template create my-template \
  --driver github.com/hyve-modules/civo \
  --driver-version v1.0.0 \
  --region PHX1

Commit hyve.lock to Git

The hyve.lock file ensures reproducible module installs. Always commit it to your state repository:

git add hyve.lock
git commit -m "Lock module versions"

Use separate repositories per environment

Keep production and development state in separate Git repositories with separate credentials:

hyve git add production --repo-url https://github.com/company/hyve-prod.git
hyve git add development --repo-url https://github.com/company/hyve-dev.git

Never commit secrets

If you use .env files for local development, add them to .gitignore:

.gitignore

.env
.env.*
!.env.example

If you set env.file in hyve.yaml (via hyve config set env.file <path> or Hyve Studio — see env (optional)), this is handled for you automatically: the filename is appended to .gitignore the moment it’s set, before it’s ever written to disk.

Related

Quick Start

Complete setup walkthrough

Module System

How modules work and how to add them

CI/CD Guide

Automate reconciliation in pipelines

Git Management

Configure Git repositories