Skip to content

Install and initialise HybridOps.Core

  • Purpose: Install hyops, install prerequisites where required, initialise local runtime state, and validate workstation readiness for HybridOps.Core execution.

  • Owner: Platform operations

  • Trigger: New installation, upgrade to a new release, or workstation rebuild.

  • Impact: Until completed, init targets and modules cannot be executed reliably.
  • Severity: P3

  • Pre-reqs: HybridOps.Core release package (.tar.gz), internet connectivity, and either sudo access on Linux or Homebrew on macOS for prerequisite installation.

  • Rollback strategy: A replacement is staged and verified before activation. If installation fails after activation starts, the installer restores the previous Core installation. Removing runtime state is a separate, destructive uninstall action.

Context

HybridOps.Core is delivered as a versioned release package.

  • install.sh installs the runtime under ~/.hybridops/core/ and provides a runnable hyops command.
  • pkg/build_release.sh and pkg/verify_release.sh are the source-side release bundle path for building and validating that package before publication.
  • hyops setup installs system prerequisites as an explicit operator action.
  • hyops preflight checks prerequisite presence and target readiness without modifying the system.
  • hyops init <target> initialises target credentials and readiness markers.
  • hyops show ... gives a read-only operator view over init markers, module state, and environment posture.
  • hyops test role ... runs collection role smoke tests through the runtime instead of an ad-hoc local harness.

Long-form reference and contracts are published on the docs site; the runtime ships command discovery via --help.

Preconditions and safety checks

  • Confirm operation on the intended workstation and user account.
  • Confirm the release package version matches the intended environment.
  • Verify package integrity (checksum/signature) where provided.
  • Confirm sudo is available for the optional /usr/local/bin/hyops system wrapper.
  • On Linux or Windows WSL2, confirm sudo is available for prerequisite installation.
  • On macOS, confirm Homebrew is installed and available to the logged-in user.
  • On Windows, confirm the selected distribution reports version 2 in wsl --list --verbose. Run HybridOps inside Ubuntu 24.04 and keep the runtime under the Linux home directory rather than /mnt/c/.

Windows operators download and extract the Windows ZIP, then run:

Install HybridOps.cmd

The bootstrap prepares the Windows-to-WSL handoff and invokes the same install.sh used on Linux. Use --force when replacing an existing HybridOps installation. Create the Ubuntu account when prompted; installation then continues under that account. Use the desktop shortcut for subsequent sessions.

For Windows, the bootstrap covers steps 1 through 3 below. Continue at step 4 after it reports a successful installation.

Steps

1) Verify the release package

Open the checksum instructions for the workstation OS.

bash sha256sum -c hybridops-core-<version>.tar.gz.sha256

Compare the published checksum with:

bash shasum -a 256 hybridops-core-<version>.tar.gz

If no checksum is provided, record the observed checksum using the command for the workstation OS.

sha256sum hybridops-core-<version>.tar.gz

Expected result: checksum verification passes or checksum is recorded.

2) Extract the release package

mkdir -p ~/downloads/hybridops
cd ~/downloads/hybridops
tar -xzf hybridops-core-<version>.tar.gz
cd hybridops-core-<version> 2>/dev/null || cd hybridops-core

Expected result: extracted directory contains install.sh and tools/setup/.

3) Install hyops

Default installation:

  • Runtime payload: ~/.hybridops/core/app
  • Runtime venv: ~/.hybridops/core/venv
  • User wrapper: ~/.local/bin/hyops
  • Optional system wrapper: /usr/local/bin/hyops
  • Installed blueprint payload under ~/.hybridops/core/app/blueprints/ is hardened read-only; operator edits belong under ~/.hybridops/envs/<env>/config/blueprints/ via hyops blueprint init
  • Durable module inputs belong under ~/.hybridops/envs/<env>/config/modules/ and can be materialized with hyops module init

Run:

./install.sh

On macOS, the installer detects Darwin and installs the CLI without invoking Linux prerequisite setup. It may request sudo once for the optional /usr/local/bin/hyops link. The user wrapper remains available at ~/.local/bin/hyops. Homebrew prerequisite setup is performed explicitly in step 5.

On Windows WSL2, the bootstrap prepares Ubuntu and installs the CLI without installing every platform tool. Browser-assisted commands open the Windows host browser when WSL integration is available.

Optional flags:

  • --force replaces an existing installation transactionally. The candidate is staged and verified before activation; the previous installation is restored if a later installation step fails.
  • --no-system-link skips installing /usr/local/bin/hyops.
  • --setup-all runs tools/setup/setup-all.sh after installing the runtime (requires sudo on Linux; must run without sudo on macOS).

Examples:

./install.sh --force
./install.sh --force --no-system-link
./install.sh --force --setup-all

Expected result: hyops is installed and executable. The installer prints a run-record path under ~/.hybridops/logs/install/. Keep that path with any support or change record; it contains output.log and result.json.

During replacement, the installer reports verifying candidate before activating installation. Do not remove the existing installation manually. If dependency wheels in the bundle are not compatible with the workstation, the installer reports that it is using the package index and requires internet access to complete that step.

4) Confirm hyops is available

command -v hyops
hyops --version
hyops --help

If hyops is installed to ~/.local/bin and not found, open the instructions for the workstation OS.

bash echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc . ~/.bashrc command -v hyops

bash echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc . ~/.zshrc command -v hyops

Expected result: command -v hyops returns a path.

Run one setup command for the intended platform:

hyops setup gcp
hyops setup azure
hyops setup proxmox

Each target command installs base tools and Galaxy dependencies, plus the selected provider CLI where applicable. Linux and Windows WSL2 elevate only system-level stages. macOS requires Homebrew and runs setup as the logged-in user. Granular commands such as hyops setup base, hyops setup cloud-gcp and hyops setup galaxy remain available.

Expected result: required tools are installed or reported as already present. Target setup prints the directory containing its stage records under ~/.hybridops/logs/setup/<target>/.

6) Create runtime layout and validate preflight

Create the runtime layout on first use:

hyops preflight

Run strict preflight where appropriate:

hyops preflight --strict

Expected result: required checks pass. Preflight prints its run-record path under ~/.hybridops/logs/preflight/, including when a check fails.

7) Initialise required targets

Initialise only the targets required for the intended module set.

Examples:

hyops init proxmox
hyops init terraform-cloud

For targets that require vault access, ensure a password provider is available (see runbook references) and run init with a password source.

Expected result: readiness markers are created under ~/.hybridops/meta/ and run records are written under ~/.hybridops/logs/init/.

Optional state-backed inspection:

hyops show init --env dev
hyops show env --env dev

Optional role smoke command discovery:

hyops test role --help

Verification

Installation is complete when all of the following are true:

  • hyops is installed and discoverable on PATH.
  • hyops preflight completes successfully for the intended scope.
  • Required init targets are marked ready (for example ~/.hybridops/meta/proxmox.ready.json).

Post-actions and clean-up

  • Capture installation version, runtime root, and validation run records in onboarding/change records.
  • Confirm target-specific init runbooks are completed for required providers.
  • Ensure operator shell profile includes the intended hyops path and does not shadow with stale installations.

Uninstall

Do not use uninstall as the normal upgrade or recovery path. Run ./install.sh --force; its failed-upgrade path preserves or restores the previous Core installation automatically.

Remove installed wrappers:

rm -f ~/.local/bin/hyops
sudo rm -f /usr/local/bin/hyops 2>/dev/null || true

Remove runtime payload and state (destructive):

rm -rf ~/.hybridops

References