Skip to content

docs: install and README reference v0.5.2 #111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dshakes merged 2 commits into from
Nov 2, 2026
Merged

docs: install and README reference v0.5.2 #111

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
591cf31
docs: install and README reference v0.5.2
dshakes Nov 2, 2026
6815391
docs: tech-stack cites the v0.5.2 release verification
dshakes Nov 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -224,21 +224,21 @@ Traffic goes through `halo-proxy` to Anthropic, Bedrock (SigV4), Vertex, OpenAI,
<img src="assets/everywhere-light.svg" alt="macOS, Linux, Windows, Dev Containers, Codespaces and Coder workspaces, CI runners, Kubernetes via Helm" width="880">
</picture>

The current release is [v0.5.0](https://github.com/dshakes/halos/releases/tag/v0.5.0) ([CHANGELOG](CHANGELOG.md)). Or build from source: `git clone https://github.com/dshakes/halos && cd halos && make build` (builds `halo`, `halod`, `halo-shadow`, `halo-server`, `halo-proxy` and `halo-kong` into `bin/`).
The current release is [v0.5.2](https://github.com/dshakes/halos/releases/tag/v0.5.2) ([CHANGELOG](CHANGELOG.md)). Or build from source: `git clone https://github.com/dshakes/halos && cd halos && make build` (builds `halo`, `halod`, `halo-shadow`, `halo-server`, `halo-proxy` and `halo-kong` into `bin/`).

```sh
brew install dshakes/tap/halo # macOS / Linux
scoop bucket add dshakes https://github.com/dshakes/scoop-bucket && scoop install halo # Windows
npx @dshakesnotbot/halo quickstart # Node 18+, no install

# The script works everywhere; halod runs as root from a root-owned prefix
curl -fsSLO https://raw.githubusercontent.com/dshakes/halos/v0.5.0/install/install.sh
sh install.sh --version v0.5.0 # halo into ~/.local/bin
sudo sh install.sh --version v0.5.0 --prefix /usr/local --with-agent # plus halod
curl -fsSLO https://raw.githubusercontent.com/dshakes/halos/v0.5.2/install/install.sh
sh install.sh --version v0.5.2 # halo into ~/.local/bin
sudo sh install.sh --version v0.5.2 --prefix /usr/local --with-agent # plus halod
```

Also available:
- deb, rpm and apk packages from the [release assets](https://github.com/dshakes/halos/releases/tag/v0.5.0), and `install.ps1` from the [v0.5.0 tag](https://raw.githubusercontent.com/dshakes/halos/v0.5.0/install/install.ps1); a winget manifest is built but not yet submitted
- deb, rpm and apk packages from the [release assets](https://github.com/dshakes/halos/releases/tag/v0.5.2), and `install.ps1` from the [v0.5.2 tag](https://raw.githubusercontent.com/dshakes/halos/v0.5.2/install/install.ps1); a winget manifest is built but not yet submitted
- a [Dev Container Feature](features/halos) and a Coder module
- Jamf, Kandji and Intune exports
- a [GitHub Action](action.yml) and a GitLab template for CI runners
Expand Down
6 changes: 3 additions & 3 deletions docs/src/content/docs/architecture/tech-stack.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,11 +196,11 @@ The diagrams on these pages are SVGs generated by [`assets/src/build.py`](https:
| nfpm (via GoReleaser) | n/a | [`.goreleaser.yaml:97-122`](https://github.com/dshakes/halos/blob/main/.goreleaser.yaml#L97-L122) | `deb`, `rpm` and `apk` packages for `halo` and `halod`, plus the `halod` systemd unit ([`deploy/packaging/halod.service`](https://github.com/dshakes/halos/blob/main/deploy/packaging/halod.service)). |
| cosign (via GoReleaser) | n/a | [`.goreleaser.yaml:159-171`](https://github.com/dshakes/halos/blob/main/.goreleaser.yaml#L159-L171) | Keyless `sign-blob` of `checksums.txt` and keyless `sign` of images. |
| syft (via GoReleaser) | n/a | [`.goreleaser.yaml:157-158`](https://github.com/dshakes/halos/blob/main/.goreleaser.yaml#L157-L158) | SBOMs for archives (needs `syft` on `PATH`). |
| Helm chart `halos` | chart `0.5.0`, `kubeVersion >=1.27.0-0` | [`deploy/helm/halos/Chart.yaml`](https://github.com/dshakes/halos/blob/main/deploy/helm/halos/Chart.yaml) | `halo-server`, `halo-proxy`, `halo-shadow`, an optional OTel collector and the Kong plugin CR. |
| Helm chart `halos` | chart `0.5.2`, `kubeVersion >=1.27.0-0` | [`deploy/helm/halos/Chart.yaml`](https://github.com/dshakes/halos/blob/main/deploy/helm/halos/Chart.yaml) | `halo-server`, `halo-proxy`, `halo-shadow`, an optional OTel collector and the Kong plugin CR. |
| Docker Compose | v2 | [`deploy/compose/`](https://github.com/dshakes/halos/tree/main/deploy/compose), [`deploy/observability/`](https://github.com/dshakes/halos/tree/main/deploy/observability) | `make demo` (the whole stack, seeded from `examples/acme-corp`) and the observability stack. |

:::note[Release signing is verified for v0.5.0]
The `packaging` job in [`ci.yml`](https://github.com/dshakes/halos/blob/main/.github/workflows/ci.yml) runs GoReleaser as a snapshot with `--skip=publish,sign,sbom,docker`. The tag-triggered [`release.yml`](https://github.com/dshakes/halos/blob/main/.github/workflows/release.yml) runs GoReleaser for real, and its `verify` job checks the published release. For v0.5.0 (run 41254767603) it verified the keyless cosign bundle on `checksums.txt`, the archive checksums, the build-provenance attestation, the cosign signatures on the `ghcr.io/dshakes` images, the FIPS archive and the OCI chart signature, then stopped on a missing directory before its remaining checks (fixed in #95); the chart's version, appVersion and default images, `install.sh`, and the Homebrew and Scoop manifests were then checked by hand against the published release. Not Authenticode-signed; the winget manifest is built but not submitted.
:::note[Release signing is verified for v0.5.2]
The `packaging` job in [`ci.yml`](https://github.com/dshakes/halos/blob/main/.github/workflows/ci.yml) runs GoReleaser as a snapshot with `--skip=publish,sign,sbom,docker`. The tag-triggered [`release.yml`](https://github.com/dshakes/halos/blob/main/.github/workflows/release.yml) runs GoReleaser for real, and its `verify` job checks the published release. For v0.5.2 (run 41381218298) its `verify` job passed every check: the keyless cosign bundle on `checksums.txt`, the archive checksums, the build-provenance attestation, the cosign signatures on the `ghcr.io/dshakes` images, the FIPS archive, the OCI chart signature, version and default images, `install.sh`, and the Homebrew and Scoop manifests. Its `npm` job published `@dshakesnotbot/halo` and the six platform packages with npm provenance. Not Authenticode-signed; the winget manifest is built but not submitted.
:::

## CI and quality tooling
Expand Down
28 changes: 14 additions & 14 deletions docs/src/content/docs/getting-started/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@ description: Install halo and halod on macOS, Linux and Windows, in CI, in dev c
<img class="diagram dark:sl-hidden" src="/halos/diagrams/everywhere-light.svg" alt="macOS, Linux, Windows, Dev Containers, Codespaces and Coder workspaces, CI runners and Kubernetes." width="880" />
<img class="diagram light:sl-hidden" src="/halos/diagrams/everywhere-dark.svg" alt="macOS, Linux, Windows, Dev Containers, Codespaces and Coder workspaces, CI runners and Kubernetes." width="880" />

**`halo`** is the CLI you run in CI and on your workstation. **`halod`** is the fleet agent; it runs as root on each machine and applies the ring's signed release. Every channel below installs the same checksummed archives from a GitHub release. Always pin a version in automation; `v0.5.0` below is the current release.
**`halo`** is the CLI you run in CI and on your workstation. **`halod`** is the fleet agent; it runs as root on each machine and applies the ring's signed release. Every channel below installs the same checksummed archives from a GitHub release. Always pin a version in automation; `v0.5.2` below is the current release.

:::note[Release status]
[`v0.5.0`](https://github.com/dshakes/halos/releases/tag/v0.5.0) is the current release (`v0.1.0` was published without its Homebrew formula, Scoop manifest and provenance attestation; see the changelog; `v0.1.1` superseded it). Every channel below installs from it: binaries, deb/rpm/apk packages, `install.sh`/`install.ps1`, Homebrew (`dshakes/homebrew-tap`), Scoop (`dshakes/scoop-bucket`), signed checksums and signed ghcr.io images, all verified by the release workflow after publishing; winget is built but not submitted. The [changelog](https://github.com/dshakes/halos/blob/main/CHANGELOG.md#030---2026-10-23) states what is GA and what is supported but not yet field-verified. Or [build from source](#from-source).
[`v0.5.2`](https://github.com/dshakes/halos/releases/tag/v0.5.2) is the current release (`v0.1.0` was published without its Homebrew formula, Scoop manifest and provenance attestation; see the changelog; `v0.1.1` superseded it). Every channel below installs from it: binaries, deb/rpm/apk packages, `install.sh`/`install.ps1`, Homebrew (`dshakes/homebrew-tap`), Scoop (`dshakes/scoop-bucket`), signed checksums and signed ghcr.io images, all verified by the release workflow after publishing; winget is built but not submitted. The [changelog](https://github.com/dshakes/halos/blob/main/CHANGELOG.md#030---2026-10-23) states what is GA and what is supported but not yet field-verified. Or [build from source](#from-source).
:::

## macOS
Expand All @@ -21,17 +21,17 @@ brew install dshakes/tap/halo # formula in github.com/dshakes/ho
Or the script, which works on macOS and Linux and needs no sudo:

```sh
curl -fsSLO https://raw.githubusercontent.com/dshakes/halos/v0.5.0/install/install.sh
sh install.sh --version v0.5.0 # halo into ~/.local/bin; tells you if that is not on PATH
curl -fsSLO https://raw.githubusercontent.com/dshakes/halos/v0.5.2/install/install.sh
sh install.sh --version v0.5.2 # halo into ~/.local/bin; tells you if that is not on PATH
```

`install.sh` verifies `checksums.txt` against its cosign signature when `cosign` is on `PATH`. Without cosign it warns loudly and trusts only the sha256 checksums. It then verifies each archive. `--prefix DIR` changes the install location; `--with-agent` adds `halod`.

## Linux

```sh
curl -fsSLO https://github.com/dshakes/halos/releases/download/v0.5.0/halo_0.5.0_linux_amd64.deb
sudo apt install ./halo_0.5.0_linux_amd64.deb # also .rpm / .apk, arm64, and the halod_* packages
curl -fsSLO https://github.com/dshakes/halos/releases/download/v0.5.2/halo_0.5.2_linux_amd64.deb
sudo apt install ./halo_0.5.2_linux_amd64.deb # also .rpm / .apk, arm64, and the halod_* packages
```

The `halo` and `halod` packages (deb, rpm, apk) install to `/usr/bin`. `halod` ships a systemd unit and `/etc/halos/`, but is **never enabled or enrolled** by the package. You write `/etc/halos/halod.yaml`, then run `systemctl enable --now halod`. `install.sh` works on Linux too.
Expand All @@ -43,10 +43,10 @@ scoop bucket add dshakes https://github.com/dshakes/scoop-bucket
scoop install halo
```

Or [`install.ps1`](https://raw.githubusercontent.com/dshakes/halos/v0.5.0/install/install.ps1) from the release tag, from an **elevated** PowerShell:
Or [`install.ps1`](https://raw.githubusercontent.com/dshakes/halos/v0.5.2/install/install.ps1) from the release tag, from an **elevated** PowerShell:

```powershell
.\install.ps1 -Version v0.5.0 -WithAgent # to $env:ProgramFiles\Halos
.\install.ps1 -Version v0.5.2 -WithAgent # to $env:ProgramFiles\Halos
```

## npm (any OS)
Expand Down Expand Up @@ -86,9 +86,9 @@ sudo halod service install --start # print the unit first: halod service
GitHub Actions:

```yaml
- uses: dshakes/halos@v0.5.0
- uses: dshakes/halos@v0.5.2
with:
version: v0.5.0 # required; there is no "latest"
version: v0.5.2 # required; there is no "latest"
# apply: "true" # run `halod once` for a fixed ring (Linux/macOS, uses sudo)
# registry: ghcr.io/acme/halos-releases
# org: acme
Expand All @@ -101,8 +101,8 @@ GitLab CI:

```yaml
include:
- remote: https://raw.githubusercontent.com/dshakes/halos/v0.5.0/deploy/ci/gitlab/halos.gitlab-ci.yml
variables: {HALOS_VERSION: v0.5.0}
- remote: https://raw.githubusercontent.com/dshakes/halos/v0.5.2/deploy/ci/gitlab/halos.gitlab-ci.yml
variables: {HALOS_VERSION: v0.5.2}
policy-check:
extends: .halos
script: [halo validate]
Expand All @@ -114,7 +114,7 @@ policy-check:
helm install halos deploy/helm/halos --namespace halos --create-namespace
```

The chart runs `halo-server`, `halo-proxy` and `halo-shadow`, with an optional OTel collector and a Kong plugin resource. Images default to `ghcr.io/dshakes/halo-*:<chart appVersion>` (currently 0.5.0); to run a different release, set each component's `image.tag` (for example `--set server.image.tag=0.1.1`). See [production deployment](/halos/guides/production-deployment/).
The chart runs `halo-server`, `halo-proxy` and `halo-shadow`, with an optional OTel collector and a Kong plugin resource. Images default to `ghcr.io/dshakes/halo-*:<chart appVersion>` (currently 0.5.2); to run a different release, set each component's `image.tag` (for example `--set server.image.tag=0.1.1`). See [production deployment](/halos/guides/production-deployment/).

## Components

Expand Down Expand Up @@ -167,7 +167,7 @@ See [security model](/halos/concepts/security-model/) and [production deployment

```console
$ halo version
halo 0.5.0 (commit <sha>, built <date>)
halo 0.5.2 (commit <sha>, built <date>)
$ halo --help # lists validate, release, rollout, toggle, eval, upgrade, gateway, mcp ...
```

Expand Down
Loading