> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation and releases

> Install, pin, verify, upgrade, and publish Harnest releases.

A Harnest release bundles three matching parts: the native CLI, the Python runtime wheel, and `uv`. The installer verifies the release checksum before it changes your machine.

Harnest requires **Python 3.11 or newer**. New agents and the managed fallback runtime use Python 3.12.

## Install

<CodeGroup>
  ```bash Latest release theme={null}
  curl -fsSL \
    https://raw.githubusercontent.com/Usefused/harnest/main/install.sh |
    sh
  ```

  ```bash Non-interactive theme={null}
  curl -fsSL \
    https://raw.githubusercontent.com/Usefused/harnest/main/install.sh |
    HARNEST_YES=1 sh
  ```

  ```bash Pinned release theme={null}
  curl -fsSL \
    https://raw.githubusercontent.com/Usefused/harnest/main/install.sh |
    HARNEST_VERSION=v0.1.18 sh
  ```
</CodeGroup>

Verify the CLI and managed runtime:

```bash theme={null}
harnest --version
harnest doctor
```

## Diagnose an agent

From your agent folder:

```bash theme={null}
harnest doctor .
```

`doctor` detects the framework from `config.yaml`. It checks the existing runtime environment, or a development/eval environment if runtime has not been synchronized yet. It does not install or update dependencies. Run `harnest env sync .` to create or refresh the runtime environment, then retry.

With no directory argument, `doctor` detects an agent in the current folder; otherwise it checks core packages only. `--framework adk` or `--framework langgraph` explicitly adds that framework's checks. `--python` and `HARNEST_PYTHON` select an explicit interpreter for diagnosis, and the output shows which interpreter was checked. A missing framework in the shared core runtime does not mean it is missing from an agent's isolated environment.

## Installer properties

| Property                   | Default                  | Use it for                               |
| -------------------------- | ------------------------ | ---------------------------------------- |
| `HARNEST_VERSION`          | Latest GitHub release    | Pinning a release                        |
| `HARNEST_REPO`             | `Usefused/harnest`       | Installing from a fork                   |
| `HARNEST_YES`              | Unset                    | Explicit non-interactive approval        |
| `HARNEST_INSTALL_DIR`      | `$HOME/.local/bin`       | Choosing the CLI destination             |
| `HARNEST_RUNTIME_DIR`      | `$HOME/.harnest/runtime` | Choosing the private managed runtime     |
| `HARNEST_BOOTSTRAP_PYTHON` | Auto-detected            | Requiring one exact host Python          |
| `HARNEST_PYTHON`           | Managed runtime          | Overriding Python for later CLI commands |
| `GITHUB_TOKEN`             | Unset                    | Reading a private fork's releases        |

<Note>
  You run `harnest`; you do not activate the private runtime or call `python -m harnest.cli`.
</Note>

If no Python 3.11 or newer is available, embedded `uv` installs a pinned CPython 3.12 under the Harnest data directory. It does not modify the system Python.

## Upgrade

Run the installer again to replace the CLI and its matching managed runtime. Then upgrade each project separately:

```bash theme={null}
harnest doctor
harnest upgrade path/to/agent
harnest upgrade path/to/agent --apply
harnest test path/to/agent
```

The first `upgrade` is a read-only plan. Apply handles supported source and Python-version migrations, verifies the planned source hashes, and writes backups before changing project files.

## Compatibility

Each Harnest release declares the ADK and LangGraph versions it supports.
Authored dependencies live in the project's `pyproject.toml`; environment sync
resolves them with the Harnest release, selected framework, extensions, task
runtime, and all transitives. Production runtime, development, and eval profiles
have separate hash-verified locks so compiled deployment artifacts exclude
pytest, evaluation, and unused MCP packages.

| Check                                    | Command                                            |
| ---------------------------------------- | -------------------------------------------------- |
| CLI and runtime match                    | `harnest doctor`                                   |
| Project environment is current           | `harnest env sync <project>`                       |
| Development environment is current       | `harnest env sync <project> --profile development` |
| Source works with the selected framework | `harnest test <project>`                           |
| Artifact is reproducible                 | `harnest compile <project>`                        |

## Publish a release

Release publishing is a maintainer workflow:

<Steps>
  <Step title="Run the complete gate">
    ```bash theme={null}
    make quality
    ```
  </Step>

  <Step title="Prepare release notes and version metadata">
    Keep the native CLI, embedded wheel, and compatibility metadata on the same version.
  </Step>

  <Step title="Tag the release">
    The release workflow builds the supported macOS and Linux archives, creates `checksums.txt`, and publishes the artifacts.
  </Step>

  <Step title="Verify a clean install">
    Test the public installer and run `harnest doctor` on at least one supported platform.
  </Step>
</Steps>

<Warning>
  Do not publish a CLI with a wheel from another version. The executable rejects mismatched embedded metadata.
</Warning>