HOWTO – Install and verify HybridOps.Core on a bootstrap workstation¶

This HOWTO is the operator walkthrough for installing HybridOps.Core from a release package and proving the runtime is ready to execute modules. It is written for repeatability and auditability.

Difficulty: Intro Prerequisites: A HybridOps.Core release package (.tar.gz), shell access to the workstation, internet connectivity, sudo on Linux or Windows WSL2, or Homebrew on macOS. Windows operators use Ubuntu 24.04 under WSL2 and keep the runtime in the Linux home directory.

Demo¶

A short walkthrough video is recommended for this HOWTO.

Demo: (pending)
Source: (not required; HybridOps.Core is delivered as a release package)

Context¶

HybridOps.Core is delivered as a versioned release package. The installation path is intentionally minimal:

install.sh installs hyops to a predictable location.
hyops init creates the local runtime directory and baseline state.
hyops preflight validates required tooling and environment access for the module set you plan to run.
hyops validate confirms runtime wiring before executing modules.

For the operational checklist version of this flow, see the linked runbook in References.

Steps¶

Windows users extract the release ZIP and run install-windows.cmd. The bootstrap verifies and extracts the Linux archive, prepares Ubuntu 24.04 on WSL2 and installs Core. Create the Ubuntu account when prompted. Continue at step 3 after Core is installed under that account. Use open-hybridops.cmd for subsequent sessions, or accept the optional desktop shortcut prompt.

1) Extract the release package¶

This step applies to Linux and macOS. Windows extraction is handled by the ZIP bootstrap described above.

mkdir -p ~/downloads/hybridops
cd ~/downloads/hybridops

tar -xzf hybridops-core-<version>.tar.gz
cd hybridops-core

Expected result: the extracted directory contains install.sh and bin/hyops.

2) Install `hyops`¶

This step applies to Linux and macOS. On Windows, run install-windows.cmd.

The installer writes a user wrapper to ~/.local/bin/hyops and may also install the optional /usr/local/bin/hyops wrapper.

./install.sh

For an existing installation:

./install.sh --force

Replacement is transactional: the installer stages and verifies the candidate before activation and restores the previous installation if a later step fails. There is no need to uninstall first.

To avoid the system wrapper and its sudo prompt:

./install.sh --no-system-link

Expected result: hyops is installed and executable. The final output shows a run-record directory under ~/.hybridops/logs/install/. A replacement also shows verifying candidate followed by activating installation.

On macOS, the installer does not invoke Homebrew automatically. If the bundled dependency wheels are not compatible with the Mac, it uses the package index; internet access is required for that fallback.

On Windows WSL2, browser-assisted commands open the Windows host browser when WSL integration is available.

3) Ensure `hyops` is on PATH¶

If using the default install location, ensure ~/.local/bin is on PATH:

command -v hyops >/dev/null && echo "hyops on PATH" || echo "hyops not on PATH"

If required, update the appropriate shell profile.

Linux/Bash:

grep -q 'export PATH="$HOME/.local/bin:$PATH"' ~/.bashrc ||   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

. ~/.bashrc

macOS/Zsh:

grep -q 'export PATH="$HOME/.local/bin:$PATH"' ~/.zshrc || \
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
. ~/.zshrc

Expected result: command -v hyops returns a path.

4) Install workstation prerequisites¶

Run the setup command for the intended platform. The same command applies on Linux, macOS and Windows WSL2:

hyops setup gcp
# or: hyops setup azure
# or: hyops setup proxmox

Linux and Windows WSL2 elevate system stages when required. macOS setup runs as the logged-in user and requires Homebrew.

Target setup prints the directory containing its stage records under ~/.hybridops/logs/setup/<target>/.

5) Initialise the target environment¶

hyops init gcp --env dev
# or: hyops init proxmox --env dev

Expected result: the selected target reports status=ready and writes its readiness marker under ~/.hybridops/envs/dev/meta/.

6) Run preflight checks¶

hyops preflight

If you are preparing for a specific environment context:

hyops preflight --env dev

Expected result: required commands and runtime paths are checked. The command prints a run-record directory under ~/.hybridops/logs/preflight/.

7) Validate a module contract¶

hyops validate --env dev --module <module-ref>

Expected result: the selected module contract and its resolved inputs pass validation without executing infrastructure changes.

Validation¶

Installation and verification are complete when:

hyops is installed and on PATH (command -v hyops succeeds).
hyops init <target> --env <env> reports the target as ready.
hyops preflight reports the workstation is ready (or only reports known, acceptable gaps for modules you are not using).
hyops validate --module <module-ref> completes successfully for the intended module.

Troubleshooting¶

`hyops` not found after install¶

Confirm installation location:

ls -la ~/.local/bin/hyops
Confirm PATH includes the install directory:

echo "$PATH" | tr ':' '\n' | sed -n '1,120p'

Preflight reports missing tools¶

Install the missing tools indicated by hyops preflight, then re-run:

hyops preflight
hyops validate --env dev --module <module-ref>

If your installation model requires pinned versions, align your workstation tooling to the versions declared by your release (where applicable).

Uninstall¶

Use this only when removing a workstation installation. For replacement or recovery, rerun the installer with --force; failed replacement automatically retains or restores the previous Core installation.

1) Remove the installed binary:

rm -f "$(command -v hyops)"

2) Remove local runtime state (destructive):

rm -rf ~/.hybridops

3) Remove any PATH modifications you added.

References¶

License: MIT-0 for code, CC-BY-4.0 for documentation