Tech stack

This page lists everything Halos depends on, grouped by what it is for. Each entry comes from a source file in the repo, not from memory:

Go modules come from go.mod.
npm packages come from web/package.json and docs/package.json.
Container images come from deploy/ and test/uat/.
CI tooling comes from .github/workflows/ and .goreleaser.yaml.

Language and runtime

Piece	Version	Where it is pinned	Notes
Go language	`go 1.25.0`	`go.mod:3`	Minimum language version.
Go toolchain	`go1.26.6`	`go.mod:5`	CI uses `go-version-file: go.mod` (`ci.yml`).
Go build images	`golang:1.25`	`deploy/compose/Dockerfile.svc:2`	Demo and compose builds. The eval images pin `golang:1.25-bookworm` by digest (`evals/images/claude/Dockerfile:4`).
Node.js	`22`	`ci.yml` (`setup-node` with `node-version: 22`), `docs.yml`	Builds the web console and the docs only. No Node runs in a Halos binary at run time.
Binaries	`CGO_ENABLED=0`, `-trimpath`	`.goreleaser.yaml:16-20`	Static binaries for darwin, linux and windows, amd64 and arm64. `halo-kong` is linux only.

Most of the core is the Go standard library:

Reverse proxy: net/http and net/http/httputil.ReverseProxy (cmd/halo-proxy/proxy.go:95-107).
Signatures: crypto/ed25519 for release, pointer and kill-list signatures (internal/bundle/sign.go, internal/gateway/killswitch.go:44-75).
Hashing: crypto/sha256 for content addressing and assignment hashing (internal/assign/assign.go:16-19).
Bundles: archive/tar for the release bundle (internal/release/release.go:191-223).
Logs: log/slog for structured logs.

Go modules

CLI

Module	Version	Used for	Used by
`github.com/spf13/cobra`	`v1.10.2`	The `halo` command tree; the CLI reference pages are generated from it.	`cmd/halo`, `internal/docgen`
`github.com/spf13/pflag`	`v1.0.9`	Reading flag definitions when generating the CLI reference.	`internal/docgen`

Policy and configuration

Module	Version	Used for	Used by
`gopkg.in/yaml.v3`	`v3.0.1`	Policy YAML with strict decoding and line-numbered errors (`internal/policy/load.go:143-144`), binary configs, and comment-preserving YAML edits for PRs.	`cmd/halo`, `cmd/halo-proxy`, `cmd/halo-shadow`, `cmd/halod`, `internal/cloudagents/workflow`, `internal/copilot`, `internal/eval`, `internal/gateway/kong`, `internal/intent`, `internal/mcpserver`, `internal/policy`, `internal/promote`, `internal/rollout`, `internal/server`, `internal/telemetry`, `internal/upgrade`, `internal/yamledit`; tests: `internal/gateway/adapters`
`github.com/pelletier/go-toml/v2`	`v2.4.3`	Codex `config.toml` rendering, the rendered-config backstop, toggle fragment merges, reading users’ Codex MCP servers for drift, and reading Codex settings for the sandbox/egress posture.	`cmd/halod`, `internal/harness`, `internal/harness/codex`, `internal/release`, `internal/toggle`
`github.com/santhosh-tekuri/jsonschema/v6`	`v6.0.3`	Tests that validate policy documents against `schemas/*.schema.json`.	tests: `internal/policy`
`howett.net/plist`	`v1.0.1`	macOS MDM configuration profile export.	`internal/delivery/mdm`

Crypto and supply chain

Module	Version	Used for	Used by
`oras.land/oras-go/v2`	`v2.6.2`	Pushing and pulling release bundles and signed ring pointers as OCI artifacts, and fetching digest-pinned supply-chain artifacts (`internal/bundle/bundle.go:50-125`).	`cmd/halo`, `cmd/halod`, `internal/bundle`, `internal/server`, `internal/supplychain`
`github.com/opencontainers/image-spec`	`v1.1.1`	OCI manifest and descriptor types.	`internal/bundle`, `internal/supplychain`; tests: `cmd/halo`, `cmd/halod`
`github.com/opencontainers/go-digest`	`v1.0.0`	Content digests for blobs and pointer statements.	`internal/bundle`, `internal/supplychain`

Signing itself uses the standard library: ed25519 primary signatures in internal/bundle/sign.go. cosign is an optional co-signer, called as an external cosign sign-blob process (internal/bundle/sign.go:103-190); it is not a Go dependency.

Identity

Module	Version	Used for	Used by
`github.com/coreos/go-oidc/v3`	`v3.21.0`	OIDC discovery and JWT / ID-token verification against the issuer’s JWKS: gateway callers (`internal/identity/oidc.go:71-91`) and console login.	`internal/identity`, `internal/server`
`github.com/go-jose/go-jose/v4`	`v4.1.4`	Halos’s own JWKS cache for OIDC verification (`internal/identity/jwks.go`), which can verify from cached keys only, so a client IP blocked for failed token exchanges cannot make `halo-server` fetch the issuer’s JWKS. Already required by go-oidc.	`internal/identity`
`golang.org/x/oauth2`	`v0.36.0`	The console’s OIDC authorization-code flow.	`internal/server`
`golang.org/x/time`	`v0.15.0`	Per-IP rate limiting of failed token attempts.	`internal/server`

Gateway

Module	Version	Used for	Used by
`github.com/Kong/go-pdk`	`v0.11.2`	The Kong Go plugin server and PDK that `halo-kong` runs on (`cmd/halo-kong/main.go:376`).	`cmd/halo-kong`
`github.com/aws/aws-sdk-go-v2`	`v1.47.0`	SigV4 signing of direct Bedrock requests (`aws/signer/v4`) (`internal/gateway/upstreamauth/bedrock.go:139-194`).	`internal/gateway/upstreamauth`; tests: `cmd/halo-proxy`
`github.com/aws/aws-sdk-go-v2/config`	`v1.33.4`	The default AWS credential chain for that signer.	`internal/gateway/upstreamauth`
`github.com/aws/aws-sdk-go-v2/credentials`	`v1.20.4`	Static credentials in the SigV4 tests.	tests: `cmd/halo-proxy`, `internal/gateway/upstreamauth`
`github.com/aws/smithy-go`	`v1.28.1`	Used by the SigV4 tests.	tests: `internal/gateway/upstreamauth`

The gateway’s data path is net/http and httputil.ReverseProxy. Vertex tokens come from the metadata server, or from a service-account JWT signed with the standard library (internal/gateway/upstreamauth/vertex.go:205-214); no Google SDK is used.

Telemetry

Module	Version	Used for	Used by
`google.golang.org/protobuf`	`v1.36.11`	Hand-encodes OTLP/HTTP protobuf with `protowire` for `halo.gateway.*` metrics (`internal/telemetry/gwmetrics/gwmetrics.go`).	`internal/telemetry/gwmetrics`
`go.opentelemetry.io/proto/otlp`	`v1.10.0`	Decodes that output in tests.	tests: `internal/telemetry/gwmetrics`

No OpenTelemetry SDK runs in a Halos binary. The collector, ClickHouse and Grafana run as containers (see Images).

Agents (MCP)

Module	Version	Used for	Used by
`github.com/modelcontextprotocol/go-sdk`	`v1.8.0`	The MCP server behind `halo mcp serve` (`internal/mcpserver/server.go:48-71`).	`cmd/halo`, `internal/mcpserver`

Storage (HA)

Module	Version	Used for	Used by
`github.com/jackc/pgx/v5`	`v5.10.0`	Postgres driver behind `database/sql` (`pgx/v5/stdlib`) for the optional HA backend of `halo-server` and `halo-shadow` (ADR-0021).	`internal/pgstore`

The file backend (JSONL under --data-dir) needs no module; without --database-url-file the driver is linked but never opened.

Platform

Module	Version	Used for	Used by
`golang.org/x/sys`	`v0.41.0`	Windows ACL and ownership checks on halod’s trusted files and private files (`windows` build tag only).	`cmd/halod`, `internal/fsutil`

Web console

web/package.json is a React single-page app built with Vite. With the webdist build tag it is embedded in halo-server (.goreleaser.yaml:29-33).

Package	Range	Role
`react`	`^19.3.0`	UI
`react-dom`	`^19.3.0`	DOM renderer
`@tanstack/react-query`	`^5.104.0`	Server state and caching for the `/api/v1` calls
`zod`	`^4.6.5`	Runtime validation of API responses
`vite`	`^8.3.1`	Dev server and bundler
`@vitejs/plugin-react`	`^6.1.1`	React support for Vite
`tailwindcss`	`^4.3.3`	Styling
`@tailwindcss/vite`	`^4.3.3`	Tailwind Vite plugin
`typescript`	`^7.0.2`	Type checking (`tsc --noEmit` in `npm run build`)
`@types/react`	`^19.3.0`	React types
`@types/react-dom`	`^19.3.0`	React DOM types
`@types/node`	`^22.20.5`	Node types for the Playwright config
`@playwright/test`	`^1.63.0`	Headless Chromium click-through of the console (`make demo-e2e`)

Docs site

docs/package.json is Astro with Starlight, deployed to GitHub Pages by docs.yml (withastro/action).

Package	Range	Role
`astro`	`^7.3.5`	Static site generator
`@astrojs/starlight`	`^0.42.4`	Docs theme, search, sidebar
`@fontsource-variable/inter`	`^5.3.0`	Body font
`@fontsource-variable/jetbrains-mono`	`^5.3.0`	Code font
`@fontsource-variable/sora`	`^5.3.0`	Display font

The diagrams on these pages are SVGs generated by assets/src/build.py, with light and dark versions. They are not Mermaid.

Container images

Image	Tag / digest	Where	Role
`gcr.io/distroless/static-debian12:nonroot`	`sha256:afa5c872…`	`deploy/docker/Dockerfile.service:4`	Base image of the released `halo-server`, `halo-proxy` and `halo-shadow` images (`.goreleaser.yaml:43-67`).
`kong`	`3.9`, `sha256:12972ce1…`	`deploy/docker/Dockerfile.kong:6`, `scripts/uat-kong.sh:15-16`	Kong OSS that `halo-kong` runs inside (`ghcr.io/dshakes/kong-halo`). The compose stack uses the unpinned `kong:3.9` (`deploy/compose/Dockerfile.kong:9`).
`otel/opentelemetry-collector-contrib`	`0.161.0`, `sha256:fd328de2…`	`deploy/observability/docker-compose.yml:28`, `deploy/helm/halos/values.yaml:283`	OTLP receivers to ClickHouse. Its config is generated by `internal/telemetry` (`collector.go:157-282`).
`clickhouse/clickhouse-server`	`26.9.7.9`, `sha256:1f9c29a7…`	`deploy/observability/docker-compose.yml:16`	Evidence store; schema in `deploy/observability/clickhouse/schema.sql`.
`grafana/grafana`	`13.2.3`, `sha256:b28bae15…`	`deploy/observability/docker-compose.yml:73`	Dashboards (`deploy/observability/grafana/dashboard.json`).
`registry.k8s.io/git-sync/git-sync`	`v4.4.0`	`deploy/helm/halos/values.yaml:37`	Keeps the served policy directory in sync in the Helm chart.
`registry:2`	`2`	`deploy/compose/docker-compose.demo.yml:23`, `ci.yml` (`e2e` service)	OCI registry for the demo and the e2e tests.
`alpine`	`3.20` / `3.22`	`deploy/compose/Dockerfile.svc:10`, `test/uat/k8s/Dockerfile:4`	Runtime images for the demo and UAT.
`node`	`22-alpine`, `22-bookworm-slim` (digest)	`deploy/compose/demo/Dockerfile.console:4`, `evals/images/claude/Dockerfile:6`	Builds the console in the demo; base image of the eval images that run the real CLIs.

Packaging and deploy

Tool	Version	Where	What it does
GoReleaser	`~> v2` (config `version: 2`)	`.goreleaser.yaml`, `ci.yml` `packaging` job	Archives, checksums, multi-arch images (`dockers_v2`), Homebrew, Scoop and a winget manifest.
nfpm (via GoReleaser)	n/a	`.goreleaser.yaml:97-122`	`deb`, `rpm` and `apk` packages for `halo` and `halod`, plus the `halod` systemd unit (`deploy/packaging/halod.service`).
cosign (via GoReleaser)	n/a	`.goreleaser.yaml:159-171`	Keyless `sign-blob` of `checksums.txt` and keyless `sign` of images.
syft (via GoReleaser)	n/a	`.goreleaser.yaml:157-158`	SBOMs for archives (needs `syft` on `PATH`).
Helm chart `halos`	chart `0.3.0`, `kubeVersion >=1.27.0-0`	`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/`, `deploy/observability/`	`make demo` (the whole stack, seeded from `examples/acme-corp`) and the observability stack.

CI and quality tooling

Tool	Version	Where
golangci-lint	`v2.14.0` (golangci-lint-action `v8.0.0`)	`ci.yml` `lint`
govulncheck	govulncheck-action `v1.1.0`	`ci.yml` `vuln`; `make vuln` runs `govulncheck@latest` (`Makefile:18-19`)
`go test -race`	toolchain from `go.mod`	`ci.yml` `test`, plus macOS and Windows in the `cross` job
`go mod tidy` drift check	n/a	`ci.yml` `tidy`
shellcheck	runner default	`ci.yml` `packaging` (`install/install.sh`, `deploy/packaging/*.sh`)
GitHub Actions	pinned by commit SHA	every `uses:` in `.github/workflows/`

Test tooling

Tool	Version	Where	What it tests
kind	`v0.27.0` (`go install sigs.k8s.io/kind@v0.27.0`)	`ci.yml` `uat-k8s`, `scripts/uat-k8s.sh`	The Helm chart on a throwaway cluster, with user stories in `test/uat/k8s`.
Kong OSS	`3.9.x` by digest	`scripts/uat-kong.sh:15-16`, `test/uat/kong`	`halo-kong` inside a real DB-less Kong.
Real CLIs	acme pins	`scripts/uat-clis.sh`, `test/uat/clis_test.go`	Claude Code, Codex, Gemini CLI and Copilot CLI behind `halo-proxy`.
Mock OIDC IdP	in repo	`deploy/compose/mockidp`, `internal/identity/identitytest`	JWT issuance and JWKS for the demo, e2e and unit tests.
Mock model APIs	in repo	`deploy/compose/mockllm`, `test/uat/mock`	Provider wire formats without API keys.
vhs	not pinned	`assets/tapes/`, `docs/scripts/record-media.sh`	Records the README GIFs and the site’s terminal clips from the real binaries.
Headless Chrome over CDP	not pinned	`docs/scripts/record-console.mjs`	Records the console walkthrough on `make demo`.