Distribution¶

Every channel below installs the same cortex binary built from this repository. Release artifacts, source builds, and make build all enable the cortex_vectors build tag (functional zero-CGO SQLite BLOB vector path); see Build From Source for what happens without it. For current version numbers and artifacts, always consult the Releases page.

Channels at a Glance¶

Channel	Command	Managed by
Homebrew (macOS / Linux)	`brew tap` + `brew install cortex`	GoReleaser → `lleontor705/homebrew-tap`
Go toolchain	`go install .../cmd/cortex@latest`	You
Release binary	Download + checksum verify	GoReleaser (GitHub Releases)
Source build	`make build`	You
Container image	`docker pull ghcr.io/lleontor705/cortex`	Release workflow (multi-arch)

Homebrew (macOS / Linux)¶

Release automation publishes the formula to the lleontor705/homebrew-tap repository (GoReleaser brews: in .goreleaser.yaml, written to Formula/cortex.rb). The in-repo review copy lives at packaging/homebrew/cortex.rb.

brew tap lleontor705/homebrew-tap
brew install cortex

The tap-qualified one-liner works too:

brew install lleontor705/tap/cortex

Upgrade later with brew update && brew upgrade cortex. The formula downloads the prebuilt release archive for your OS/architecture and verifies its sha256; brew install --HEAD cortex builds the latest main commit from source instead (requires Go).

Go Install¶

The module path comes from go.mod (github.com/lleontor705/cortex/v2):

go install github.com/lleontor705/cortex/v2/cmd/cortex@latest

go install compiles without build tags, so this variant ships the degraded sqlite_blob vector stub (lexical FTS5 retrieval only). cortex doctor reports the degraded state. Enable the functional vector path with:

go install -tags cortex_vectors github.com/lleontor705/cortex/v2/cmd/cortex@latest

Release Binary¶

Each release contains cortex_<version>_<os>_<arch>.tar.gz archives (zip for Windows) for macOS, Linux, and Windows on amd64/arm64, plus a checksums.txt manifest.

curl -LO https://github.com/lleontor705/cortex/releases/download/<tag>/checksums.txt
curl -LO https://github.com/lleontor705/cortex/releases/download/<tag>/<archive>

# Linux (GNU coreutils)
sha256sum --ignore-missing -c checksums.txt

# macOS
grep '<archive>' checksums.txt | shasum -a 256 -c -

Then extract the archive and place cortex on your PATH.

Verify Signatures¶

Each release also carries a Sigstore bundle for every archive and for checksums.txt (<asset>.sigstore). The bundles are produced keylessly: the release workflow authenticates through GitHub's OIDC token, Fulcio issues a short-lived certificate, and the entry lands in the Rekor transparency log — this repository stores no signing key or signing secret.

Install cosign, then verify the checksum manifest:

curl -LO https://github.com/lleontor705/cortex/releases/download/<tag>/checksums.txt
curl -LO https://github.com/lleontor705/cortex/releases/download/<tag>/checksums.txt.sigstore

cosign verify-blob \
  --bundle checksums.txt.sigstore \
  --certificate-identity "https://github.com/lleontor705/cortex/.github/workflows/release.yml@refs/tags/<tag>" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  checksums.txt

Once checksums.txt verifies, sha256sum --ignore-missing -c checksums.txt (see Release Binary) authenticates every archive it lists. An individual archive can also be verified directly by swapping in <archive> and its <archive>.sigstore bundle.

Notes:

The bundle is self-contained (certificate, signature, and Rekor entry in one file), so no COSIGN_REPOSITORY setting is needed: signatures ship as release assets rather than in an OCI registry.
A release cut by workflow_dispatch signs from the dispatch branch, so its identity ends with @refs/heads/<branch>. To accept either form, replace --certificate-identity with --certificate-identity-regexp 'https://github\.com/lleontor705/cortex/\.github/workflows/release\.yml@'.
SPDX SBOMs (<archive>.sbom.json, generated by syft through GoReleaser) are attached to the same release page.

Build From Source¶

Requirements: Go (the go.mod toolchain directive pins the exact version CI enforces) and Make.

git clone https://github.com/lleontor705/cortex.git
cd cortex
make build        # outputs bin/cortex with -tags cortex_vectors (default)
make install      # optional: go install ./cmd/cortex into GOPATH/bin

make build passes -tags cortex_vectors unconditionally, so a plain make build already includes the functional zero-CGO vector adapter. A bare go build ./cmd/cortex without the tag still compiles but wires the degraded vector stub; cortex doctor explains the difference. CI, the GoReleaser archives, and the Homebrew head build all use the same tagged configuration.

Docker (GHCR, Multi-Arch)¶

The release workflow publishes the server image (HTTP API + embedded web UI) to GitHub Container Registry for linux/amd64 and linux/arm64:

docker pull ghcr.io/lleontor705/cortex:latest

Tags mirror the release metadata: latest, the git tag, the branch, and sha-<commit>. The image is built from docker/Dockerfile. docker compose up -d uses the same image; see INSTALLATION.md for environment variables, ports, and the web access key flow.

Plugin Packages¶

Two editor/agent plugin packages ship in this repository and are verified by their own harnesses:

# OpenCode plugin (TypeScript, Vitest; Node >= 24, own lockfile)
cd plugin/opencode && npm ci && npm test

# Claude Code plugin (hooks contract harness; needs bash, jq, python3, timeout)
bash plugin/claude-code/scripts/hooks_test.sh

See PLUGINS.md for plugin structure and lifecycle hooks. Neither package is published to npm; they are distributed from this repository.

Contribution & Release Conventions¶

Pre-push hook: Husky runs golangci-lint run ./... followed by go test -v ./...; a push fails fast if either gate fails.
Pull requests: PRs validate against the develop and master targets. The body must contain Closes #N, Fixes #N, or Resolves #N for an issue labeled status:approved, and the PR needs exactly one type:* label.
Releases: tag pushes run .github/workflows/release.yml — GoReleaser builds the archives, checksums.txt, and the Homebrew tap commit; the same workflow publishes the GHCR image.