From 725dcc295c4fd30c45240f79a295d161bffb06ca Mon Sep 17 00:00:00 2001 From: Michal Jacovi Date: Sat, 21 Nov 2026 13:05:03 +0200 Subject: [PATCH 1/5] feat: Release Windows builds of agentop and cortex as .zip Part of #1520. release-binaries.yaml builds windows/amd64 and windows/arm64 too: agentop.exe and cortex.exe (the same profile tags as the other cortex builds), each in its own .zip, named like the other archives (agentop__windows_.zip). They are required like the other archives, listed in checksums.txt, attested, and uploaded with them. The release notes say Windows is a preview. docs/getting-started.md gets the Windows steps: download, check, unzip onto PATH, `cortex --local` in one terminal and `agentop observe` in another, and what does not run there yet. install.sh tells a Windows shell (MINGW, MSYS, Cygwin) to use the .zip instead. Needs #2048: agentop builds for Windows only with it. Assisted-By: Claude (Anthropic AI) Signed-off-by: Michal Jacovi --- .github/workflows/release-binaries.yaml | 50 +++++++++++++++++-------- docs/getting-started.md | 14 +++++++ scripts/install.sh | 1 + 3 files changed, 49 insertions(+), 16 deletions(-) diff --git a/.github/workflows/release-binaries.yaml b/.github/workflows/release-binaries.yaml index 639fb3c28..f9d320378 100644 --- a/.github/workflows/release-binaries.yaml +++ b/.github/workflows/release-binaries.yaml @@ -135,7 +135,7 @@ jobs: with: go-version-file: cmd/cortex/go.mod - - name: Build binaries (linux/darwin, amd64/arm64) + - name: Build binaries (linux/darwin/windows, amd64/arm64) run: | set -euo pipefail mkdir -p dist @@ -151,35 +151,46 @@ jobs: ":${full_tags}" ) + # pack : a .tar.gz, or on Windows a + # .zip of the .exe (#1520), the format a Windows user can open without tools. + pack() { + local os="$1" archive="$2" bin="$3" + if [ "${os}" = windows ]; then + ( cd dist && zip -q "${archive#dist/}.zip" "${bin}" ) + else + tar -C dist -czf "${archive}.tar.gz" "${bin}" + fi + rm -f "dist/${bin}" + } + build_proxy() { local variant="$1" tags="$2" os="$3" arch="$4" local suffix=""; [ -n "${variant}" ] && suffix="-${variant}" + local bin="cortex"; [ "${os}" = windows ] && bin="cortex.exe" # ${TAG}, not ${VERSION}: the filename has to match the download URL the # installer builds from the release tag. They are the same string for a # v* tag and differ only on the rolling channel release. - local archive="dist/cortex${suffix}_${TAG}_${os}_${arch}.tar.gz" echo "==> cortex${suffix} ${os}/${arch}" ( cd cmd/cortex && \ GOWORK=off CGO_ENABLED=0 GOOS="${os}" GOARCH="${arch}" \ go build -trimpath \ -tags "${tags}" \ -ldflags "-s -w -X main.version=${VERSION}" \ - -o "${GITHUB_WORKSPACE}/dist/cortex" . ) - tar -C dist -czf "${archive}" cortex - rm -f dist/cortex + -o "${GITHUB_WORKSPACE}/dist/${bin}" . ) + pack "${os}" "dist/cortex${suffix}_${TAG}_${os}_${arch}" "${bin}" } - for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64; do + for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do os="${target%/*}"; arch="${target#*/}" + bin="agentop"; [ "${os}" = windows ] && bin="agentop.exe" echo "==> agentop ${os}/${arch}" ( cd cmd/agentop && \ GOWORK=off CGO_ENABLED=0 GOOS="${os}" GOARCH="${arch}" \ go build -trimpath \ -ldflags "-s -w -X main.version=${VERSION}" \ - -o "${GITHUB_WORKSPACE}/dist/agentop" . ) - tar -C dist -czf "dist/agentop_${TAG}_${os}_${arch}.tar.gz" agentop - rm -f dist/agentop + -o "${GITHUB_WORKSPACE}/dist/${bin}" . ) + pack "${os}" "dist/agentop_${TAG}_${os}_${arch}" "${bin}" for entry in "${proxy_variants[@]}"; do build_proxy "${entry%%:*}" "${entry#*:}" "${os}" "${arch}" @@ -191,7 +202,9 @@ jobs: uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: dist-go - path: dist/*.tar.gz + path: | + dist/*.tar.gz + dist/*.zip if-no-files-found: error retention-days: 1 @@ -313,10 +326,11 @@ jobs: # main-latest the prune below deletes whatever dist/ lacks, so a silent gap # here would also remove the previous build's asset from the release. missing="" - for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64; do + for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do os="${target%/*}"; arch="${target#*/}" + ext="tar.gz"; [ "${os}" = windows ] && ext="zip" for name in agentop cortex; do - f="dist/${name}_${TAG}_${os}_${arch}.tar.gz" + f="dist/${name}_${TAG}_${os}_${arch}.${ext}" [ -s "${f}" ] || missing="${missing} ${f}" done done @@ -336,7 +350,7 @@ jobs: p="${TAG}_${target%/*}_${target#*/}.tar.gz" cp "dist/cortex_${p}" "dist/cortex-cpex_${p}" done - ( cd dist && sha256sum ./*.tar.gz > checksums.txt ) + ( cd dist && sha256sum ./*.tar.gz ./*.zip > checksums.txt ) ls -l dist cat dist/checksums.txt @@ -345,7 +359,9 @@ jobs: if: github.event_name == 'push' uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2 with: - subject-path: dist/*.tar.gz + subject-path: | + dist/*.tar.gz + dist/*.zip - name: Publish to GitHub Release # A main push publishes too, which is the whole point of the channel; the @@ -393,6 +409,8 @@ jobs: fi fi add 'Prebuilt `agentop` and `cortex` binaries for linux and macOS (amd64/arm64).' + add 'Windows (amd64/arm64) is a preview, as `.zip`: run `cortex --local` in a terminal.' + add '`agentop service`, `setup` and `update` are not supported there yet (#1520).' # The laptop cpex build is gone. Drop this, and the cortex-cpex_* copies above, # once no supported release ships a cpex laptop build. add 'The laptop cpex build is removed. `cortex-cpex_*` is a copy of `cortex_*`,' @@ -451,7 +469,7 @@ jobs: gh api --method PATCH "repos/${GITHUB_REPOSITORY}/git/refs/tags/${TAG}" \ -f sha="${GITHUB_SHA}" -F force=true >/dev/null fi - gh release upload "${TAG}" dist/*.tar.gz dist/checksums.txt --clobber + gh release upload "${TAG}" dist/*.tar.gz dist/*.zip dist/checksums.txt --clobber # --clobber replaces same-named assets but never deletes others, so every # name this build stops producing lingers on the rolling release: frozen at # its last build, and missing from checksums.txt, so nothing can verify it. @@ -489,7 +507,7 @@ jobs: # built. Usually the same on a main push, but it is exactly the drift the # PATCH above exists to prevent — and it made the FIRST publish create the # tag at the wrong commit, so the two paths disagreed. - gh release create "${TAG}" dist/*.tar.gz dist/checksums.txt \ + gh release create "${TAG}" dist/*.tar.gz dist/*.zip dist/checksums.txt \ --target "${GITHUB_SHA}" \ --title "${TAG}" --notes "${notes}" ${prerelease} fi diff --git a/docs/getting-started.md b/docs/getting-started.md index 7ba5e06ab..73d875b33 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -27,6 +27,20 @@ curl -fsSL https://www.rossoctl.dev/cortex/install.sh | sh -s -- --yes When setup is done, open a new terminal. The new terminal reads the new `PATH`. +### Windows (preview) + +`install.sh` and `agentop setup` don't run on Windows yet (#1520). Install by hand: + +1. From the [releases page](https://github.com/rossoctl/cortex/releases), download `agentop__windows_amd64.zip` and `cortex__windows_amd64.zip` (`arm64` on an Arm PC), and `checksums.txt`. +2. Check them in PowerShell: `Get-FileHash .\agentop_*_windows_*.zip` must match the line for that file in `checksums.txt`, and the same for `cortex`. +3. Unzip both into one folder, for example `$HOME\.local\bin`, and add that folder to your user `PATH`. +4. In one terminal, run the proxy: `cortex --local`. It writes `~/.cortex/config.yaml` on first run. Stop it with `Ctrl-C`. +5. In a second terminal, run `agentop observe`. + +Then connect Claude Code with `agentop configure claude-code enable`, or run one session through Cortex with `agentop exec -- claude`. + +Not on Windows yet: `agentop service`, `setup`, `uninstall` and `update` (they refuse and say so), so the proxy runs only while its terminal is open. Tools other than Node (`git`, `curl`, Python) inside a session don't trust the TLS bridge yet. + ## Connect your agent Connect each agent that you use. Do this one time per agent. diff --git a/scripts/install.sh b/scripts/install.sh index f7c8f6ecc..a092e3c3e 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -393,6 +393,7 @@ detect_platform() { case "$os" in Darwin) os=darwin ;; Linux) os=linux ;; + MINGW* | MSYS* | CYGWIN*) die "Windows: this installer does not run there yet; install from the release .zip (docs/getting-started.md, \"Windows (preview)\")" ;; *) die "unsupported OS: $os (the installer supports macOS and Linux)" ;; esac arch=$(uname -m) From 72c74b8b7e8088282bf13c3597011a3672238c41 Mon Sep 17 00:00:00 2001 From: Michal Jacovi Date: Sat, 21 Nov 2026 17:10:07 +0200 Subject: [PATCH 2/5] ci: Cross-build the release's Windows targets, and fix the Windows notes From an independent review of the Windows release builds: - go-ci-windows cross-builds exactly the release's Windows targets: cortex with the full profile tags and agentop, for windows/amd64 and windows/arm64, with cgo off. The release builds every platform in one loop, so a Windows build break would stop the Linux and macOS releases too; CI built only the local profile for amd64 before. The job's comment no longer says agentop doesn't build. - Release notes: uninstall is listed with the unsupported commands, as the docs do; provenance and checksums.txt are said to cover the .zip files; the PowerShell hash check is given. - getting-started: the hash check compares lower case (Get-FileHash ... .Hash.ToLower()), as checksums.txt is. - collect-install-stats.sh files the Windows .zip downloads under windows_amd64 and windows_arm64 instead of "other". Part of #1520. Assisted-By: Claude (Anthropic AI) Signed-off-by: Michal Jacovi --- .github/workflows/ci.yaml | 22 ++++++++++++++++++++-- .github/workflows/release-binaries.yaml | 9 +++++---- docs/getting-started.md | 2 +- scripts/collect-install-stats.sh | 3 +++ 4 files changed, 29 insertions(+), 7 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index ba103fb61..843134d87 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -129,8 +129,9 @@ jobs: # Windows (#1520): core and the laptop proxy must keep building, and the session archive and # cost ledger must keep writing where a directory is flushed only through a write handle and # cannot be renamed with a file open in it. Only those packages' tests run: the rest of core - # and cmd/cortex still have Unix-only tests (Setpgid, SIGUSR1), and agentop does not build - # yet. No -race: the race detector needs cgo and a C toolchain on the runner. + # and cmd/cortex still have Unix-only tests (Setpgid, SIGUSR1). agentop builds, but most of + # its tests need a Unix shell or service manager, so only a named set runs (see its step). + # No -race: the race detector needs cgo and a C toolchain on the runner. go-ci-windows: name: Go CI (Windows build, archive and ledger) runs-on: windows-latest @@ -188,6 +189,23 @@ jobs: go vet ./... go test -run 'TestRefuseUnsupported|TestProcessAlive|TestLockFile|TestWritable|TestTerminateRefusesOnWindows|TestNoRecordWanted|TestWithRecordOff|TestAddRecordOff' . + # release-binaries.yaml builds every platform in one loop, so a Windows build break would + # stop the Linux and macOS releases too, and main-latest on every merge. Build exactly its + # Windows targets here: cortex with the release's proxy variant (the full profile) and + # agentop, for amd64 and arm64, with cgo off as the release does. Keep the tags in step + # with proxy_variants there. + - name: Build the release's Windows targets + run: | + set -euo pipefail + full_tags=$(go -C scripts/profile-tags run . full) + for arch in amd64 arm64; do + echo "==> windows/${arch}" + ( cd cmd/cortex && CGO_ENABLED=0 GOOS=windows GOARCH="${arch}" \ + go build -trimpath -tags "${full_tags}" -o /dev/null . ) + ( cd cmd/agentop && CGO_ENABLED=0 GOOS=windows GOARCH="${arch}" \ + go build -trimpath -o /dev/null . ) + done + # The cpex plugin's FFI-backed code sits behind the `cpex` build tag and needs # cgo plus the pinned libcpex_ffi.a, so no other job compiles or tests it. It # runs in Alpine to link the same musl asset the authbridge-cpex image does, diff --git a/.github/workflows/release-binaries.yaml b/.github/workflows/release-binaries.yaml index f9d320378..e5eea9a3c 100644 --- a/.github/workflows/release-binaries.yaml +++ b/.github/workflows/release-binaries.yaml @@ -410,7 +410,7 @@ jobs: fi add 'Prebuilt `agentop` and `cortex` binaries for linux and macOS (amd64/arm64).' add 'Windows (amd64/arm64) is a preview, as `.zip`: run `cortex --local` in a terminal.' - add '`agentop service`, `setup` and `update` are not supported there yet (#1520).' + add '`agentop service`, `setup`, `uninstall` and `update` are not supported there yet (#1520).' # The laptop cpex build is gone. Drop this, and the cortex-cpex_* copies above, # once no supported release ships a cpex laptop build. add 'The laptop cpex build is removed. `cortex-cpex_*` is a copy of `cortex_*`,' @@ -425,8 +425,8 @@ jobs: add '`cortex-gateway_*` is the praxis-mode gateway (static on linux).' add 'Install it with `install.sh --praxis`.' fi - add 'Every tarball carries build provenance:' - add '`gh attestation verify --repo rossoctl/cortex`.' + add 'Every archive (`.tar.gz` and `.zip`) carries build provenance:' + add '`gh attestation verify --repo rossoctl/cortex`.' add '' # The rename shipped with no alias, so it has to be said somewhere a v0.7.0 # user will look. Drop this once no supported release predates it. @@ -436,7 +436,8 @@ jobs: add '`authbridge-*`); image and container names are unchanged. Setup removes the old' add 'binary once the service no longer runs it. Stop a proxy you started by hand first.' add '' - add 'Verify downloads with `sha256sum -c checksums.txt`. On macOS, clear the' + add 'Verify downloads with `sha256sum -c checksums.txt` (it lists the `.zip` files too;' + add 'on Windows compare `(Get-FileHash -Algorithm SHA256).Hash.ToLower()`). On macOS, clear the' add 'Gatekeeper quarantine after extracting: `xattr -dr com.apple.quarantine ./agentop`.' # Whoever is asked to try a release candidate lands on this page, and the # one-liner they already know will not install it. diff --git a/docs/getting-started.md b/docs/getting-started.md index 73d875b33..ab14bf508 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -32,7 +32,7 @@ When setup is done, open a new terminal. The new terminal reads the new `PATH`. `install.sh` and `agentop setup` don't run on Windows yet (#1520). Install by hand: 1. From the [releases page](https://github.com/rossoctl/cortex/releases), download `agentop__windows_amd64.zip` and `cortex__windows_amd64.zip` (`arm64` on an Arm PC), and `checksums.txt`. -2. Check them in PowerShell: `Get-FileHash .\agentop_*_windows_*.zip` must match the line for that file in `checksums.txt`, and the same for `cortex`. +2. Check them in PowerShell. `checksums.txt` has lower-case hashes, and `Get-FileHash` prints upper case, so compare `(Get-FileHash .\agentop__windows_amd64.zip -Algorithm SHA256).Hash.ToLower()` with the line for that file, and the same for `cortex`. 3. Unzip both into one folder, for example `$HOME\.local\bin`, and add that folder to your user `PATH`. 4. In one terminal, run the proxy: `cortex --local`. It writes `~/.cortex/config.yaml` on first run. Stop it with `Ctrl-C`. 5. In a second terminal, run `agentop observe`. diff --git a/scripts/collect-install-stats.sh b/scripts/collect-install-stats.sh index 69ff71662..e98a0d1a1 100755 --- a/scripts/collect-install-stats.sh +++ b/scripts/collect-install-stats.sh @@ -315,6 +315,9 @@ jq --arg date "${today}" \ elif $name | test("darwin_amd64") then "darwin_amd64" elif $name | test("linux_arm64") then "linux_arm64" elif $name | test("linux_amd64") then "linux_amd64" + # Windows .zip files (#1520), downloaded by hand: no installer fetches them. + elif $name | test("windows_arm64") then "windows_arm64" + elif $name | test("windows_amd64") then "windows_amd64" # Unanchored: v0.1 through v0.4 named this file # kagenti-extensions__checksums.txt, which an anchored ^checksums missed. # Those 24 releases were filed under "other" and read 0 installs apiece -- 79 From 8fbd841b4d257e0d5ff72c5ec958473698db405c Mon Sep 17 00:00:00 2001 From: Michal Jacovi Date: Sat, 21 Nov 2026 18:29:19 +0200 Subject: [PATCH 3/5] docs: Keep the Windows notes on main-latest, and add Unblock-File and removal From the review of #2049: - Release notes: the Windows guidance moves after the channel-specific block, which replaces the notes on main-latest, so the rolling release keeps it too. It now includes the hash check and Unblock-File. - getting-started: Unblock-File on each .zip before extracting (the binaries are unsigned, and the .zip passes its downloaded mark on, so SmartScreen may block them), and a manual Windows removal under "Undo it", where agentop uninstall is refused: disconnect the agents, stop the proxy, delete the two .exe and the PATH entry; deleting ~/.cortex separately, which deletes the retained data. Part of #1520. Assisted-By: Claude (Anthropic AI) Signed-off-by: Michal Jacovi --- .github/workflows/release-binaries.yaml | 23 +++++++++++++++++------ docs/getting-started.md | 14 +++++++++++--- 2 files changed, 28 insertions(+), 9 deletions(-) diff --git a/.github/workflows/release-binaries.yaml b/.github/workflows/release-binaries.yaml index e5eea9a3c..7a7819702 100644 --- a/.github/workflows/release-binaries.yaml +++ b/.github/workflows/release-binaries.yaml @@ -408,9 +408,8 @@ jobs: echo "::warning::Could not list the changes since the previous release; publishing ${TAG} without them." fi fi - add 'Prebuilt `agentop` and `cortex` binaries for linux and macOS (amd64/arm64).' - add 'Windows (amd64/arm64) is a preview, as `.zip`: run `cortex --local` in a terminal.' - add '`agentop service`, `setup`, `uninstall` and `update` are not supported there yet (#1520).' + add 'Prebuilt `agentop` and `cortex` binaries for linux and macOS (amd64/arm64),' + add 'and a Windows preview (see below).' # The laptop cpex build is gone. Drop this, and the cortex-cpex_* copies above, # once no supported release ships a cpex laptop build. add 'The laptop cpex build is removed. `cortex-cpex_*` is a copy of `cortex_*`,' @@ -436,9 +435,9 @@ jobs: add '`authbridge-*`); image and container names are unchanged. Setup removes the old' add 'binary once the service no longer runs it. Stop a proxy you started by hand first.' add '' - add 'Verify downloads with `sha256sum -c checksums.txt` (it lists the `.zip` files too;' - add 'on Windows compare `(Get-FileHash -Algorithm SHA256).Hash.ToLower()`). On macOS, clear the' - add 'Gatekeeper quarantine after extracting: `xattr -dr com.apple.quarantine ./agentop`.' + add 'Verify downloads with `sha256sum -c checksums.txt`, which lists the `.zip` files too.' + add 'On macOS, clear the Gatekeeper quarantine after extracting:' + add '`xattr -dr com.apple.quarantine ./agentop`.' # Whoever is asked to try a release candidate lands on this page, and the # one-liner they already know will not install it. if [ -n "${prerelease}" ]; then @@ -459,6 +458,18 @@ jobs: add 'Each binary reports its own build (`agentop --version` -> `main-`). For a' add 'supported install, use the plain one-liner, which installs the newest stable release.' fi + # Windows (#1520), after the channel-specific block above, which replaces the notes + # on main-latest: every release with Windows archives keeps this guidance. + add '' + add '## Windows (preview)' + add '' + add '`agentop_*_windows_*.zip` and `cortex_*_windows_*.zip` (amd64/arm64). No installer' + add 'runs on Windows yet: check each `.zip` with' + add '`(Get-FileHash -Algorithm SHA256).Hash.ToLower()` against `checksums.txt`,' + add 'run `Unblock-File ` on it (the binaries are unsigned, so SmartScreen may block' + add 'them otherwise), extract both onto your PATH, then run `cortex --local` in one' + add 'terminal and `agentop observe` in another. `agentop service`, `setup`, `uninstall`' + add 'and `update` are not supported there yet. See docs/getting-started.md.' if gh release view "${TAG}" >/dev/null 2>&1; then # Uploading assets does not move the tag, so on a REUSED tag the release # would keep pointing at its first-publish commit forever: the "Source diff --git a/docs/getting-started.md b/docs/getting-started.md index ab14bf508..5292828a0 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -33,9 +33,10 @@ When setup is done, open a new terminal. The new terminal reads the new `PATH`. 1. From the [releases page](https://github.com/rossoctl/cortex/releases), download `agentop__windows_amd64.zip` and `cortex__windows_amd64.zip` (`arm64` on an Arm PC), and `checksums.txt`. 2. Check them in PowerShell. `checksums.txt` has lower-case hashes, and `Get-FileHash` prints upper case, so compare `(Get-FileHash .\agentop__windows_amd64.zip -Algorithm SHA256).Hash.ToLower()` with the line for that file, and the same for `cortex`. -3. Unzip both into one folder, for example `$HOME\.local\bin`, and add that folder to your user `PATH`. -4. In one terminal, run the proxy: `cortex --local`. It writes `~/.cortex/config.yaml` on first run. Stop it with `Ctrl-C`. -5. In a second terminal, run `agentop observe`. +3. Unblock both: `Unblock-File .\agentop__windows_amd64.zip`, and the same for `cortex`. The binaries are not signed yet, and a downloaded `.zip` passes its "from the internet" mark on to what it holds, so without this SmartScreen may block them. +4. Unzip both into one folder, for example `$HOME\.local\bin`, and add that folder to your user `PATH`. +5. In one terminal, run the proxy: `cortex --local`. It writes `~/.cortex/config.yaml` on first run. Stop it with `Ctrl-C`. +6. In a second terminal, run `agentop observe`. Then connect Claude Code with `agentop configure claude-code enable`, or run one session through Cortex with `agentop exec -- claude`. @@ -140,4 +141,11 @@ To remove Cortex, run `agentop uninstall`. It asks once. Uninstall disconnects Claude Code, OpenCode, IBM Bob and Pi. It does not disconnect Codex. If you use Codex, run `agentop configure codex disable` first. +On Windows, `agentop uninstall` is not supported yet (#1520). Remove Cortex by hand: + +1. Disconnect each agent you connected: `agentop configure disable`. Then restart the agent. +2. Stop the proxy: `Ctrl-C` in its terminal. +3. Delete `agentop.exe` and `cortex.exe`, and remove their folder from your user `PATH` if you added it only for them. +4. Optional, and separate: delete `~/.cortex`. That deletes everything Cortex kept, including the session archive, the cost ledger and the TLS bridge's CA. + For more detail, read [Remove it](laptop-service.md#remove-it). From 1c47a2d8330990be366865b06d07f0a0c318f6a2 Mon Sep 17 00:00:00 2001 From: Michal Jacovi Date: Sat, 21 Nov 2026 19:15:26 +0200 Subject: [PATCH 4/5] fix: Write the CA dir as a single-quoted YAML string in the --local config From clawgenti's review of #2049: on a fresh Windows install, cortex --local wrote ca_dir as a double-quoted YAML scalar, where the \U and \. of C:\Users\\.cortex\ca are escape sequences. The config did not load ("did not find expected hexdecimal number"), the proxy exited, and every later run, and agentop, failed the same way. The value is now single-quoted, where a backslash is a plain character and the only escape is '' for a quote. It is the only value interpolated into the generated config. Tests: the CA dir round-trips through config.Load for Windows paths with \U, \. and \n, a Unix path, and one with a quote. With double quotes back, it and the two existing config tests fail with the reported error. By hand on Windows: cortex --local with an empty home writes the config, generates the CA and answers /v1/sessions. Part of #1520. Assisted-By: Claude (Anthropic AI) Signed-off-by: Michal Jacovi --- cmd/cortex/local.go | 11 ++++++++++- cmd/cortex/local_test.go | 25 +++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/cmd/cortex/local.go b/cmd/cortex/local.go index 6b04564e5..20ca3cd9f 100644 --- a/cmd/cortex/local.go +++ b/cmd/cortex/local.go @@ -9,6 +9,7 @@ import ( "log/slog" "os" "path/filepath" + "strings" "github.com/rossoctl/cortex/core/clientstate" "github.com/rossoctl/cortex/core/config" @@ -162,6 +163,14 @@ func parseBridgeCAPEM(pemBytes []byte) *x509.Certificate { return crt } +// yamlSingleQuoted is s as a YAML single-quoted scalar. In single quotes a backslash is a plain +// character and the only escape is a doubled single quote, so a Windows path such as +// C:\Users\me\.cortex\ca reads back unchanged. In double quotes \U and \. are escape sequences, +// and a fresh install's config did not load (#1520). +func yamlSingleQuoted(s string) string { + return "'" + strings.ReplaceAll(s, "'", "''") + "'" +} + // builtinConfigYAML returns the built-in --local config with caDir interpolated: a // forward-only proxy with the TLS bridge on (auto-generated CA in caDir) and // the LLM / MCP / A2A parsers, so an agent's egress is decrypted and parsed. @@ -213,7 +222,7 @@ stats: address: 127.0.0.1:47602 tls_bridge: mode: enabled - ca_dir: "` + caDir + `" + ca_dir: ` + yamlSingleQuoted(caDir) + ` generate_ca: true # passthrough_hosts is deliberately absent. Left unset, the bridge tunnels a # built-in list of developer-tooling hosts — GitHub, the Go module proxy, the diff --git a/cmd/cortex/local_test.go b/cmd/cortex/local_test.go index 5fa186ca1..65fde033b 100644 --- a/cmd/cortex/local_test.go +++ b/cmd/cortex/local_test.go @@ -27,6 +27,31 @@ import ( "github.com/rossoctl/cortex/core/session" ) +// The CA dir in the generated config reads back exactly, on every OS: a Windows path holds +// backslashes, and in a double-quoted YAML scalar \U and \. are escapes, so a fresh install on +// Windows wrote a config it could not load (#1520). A quote in the path is kept too. +func TestDemoConfig_CADirRoundTrips(t *testing.T) { + for _, caDir := range []string{ + `C:\Users\me\.cortex\ca`, + `C:\Users\new\dir\notes\x\nca`, // \n, \x and \U are escapes in double quotes + `/home/me/.cortex/ca`, + `/home/o'brien/.cortex/ca`, + } { + cortexDir := t.TempDir() + p, err := writeBuiltinConfig(cortexDir, caDir) + if err != nil { + t.Fatalf("%s: writeBuiltinConfig: %v", caDir, err) + } + cfg, err := config.Load(p) + if err != nil { + t.Fatalf("%s: Load: %v", caDir, err) + } + if cfg.TLSBridge.CADir != caDir { + t.Errorf("CADir = %q, want %q", cfg.TLSBridge.CADir, caDir) + } + } +} + // writeBuiltinConfig must produce a config file in cortexDir that loads, presets, // and validates cleanly and describes a forward-only TLS-bridge observe // pipeline pointed at caDir — otherwise --local would fail at boot instead of From 7e70a80e8cb926ffb445104db059d5ab70fca85a Mon Sep 17 00:00:00 2001 From: Michal Jacovi Date: Sat, 21 Nov 2026 19:44:25 +0200 Subject: [PATCH 5/5] docs: Say to open a new terminal after the PATH step on Windows From the review of #2049: an open PowerShell keeps the old PATH, so the Windows steps, and the release notes' Windows block, now say to run the next commands in a new terminal, as the Linux and macOS section does. getting-started also says what to do when cortex --local can't parse a ~/.cortex/config.yaml written by an earlier Windows build: delete it, and Cortex writes a fresh one. Part of #1520. Assisted-By: Claude (Anthropic AI) Signed-off-by: Michal Jacovi --- .github/workflows/release-binaries.yaml | 4 ++-- docs/getting-started.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/release-binaries.yaml b/.github/workflows/release-binaries.yaml index 7a7819702..910f61c43 100644 --- a/.github/workflows/release-binaries.yaml +++ b/.github/workflows/release-binaries.yaml @@ -467,8 +467,8 @@ jobs: add 'runs on Windows yet: check each `.zip` with' add '`(Get-FileHash -Algorithm SHA256).Hash.ToLower()` against `checksums.txt`,' add 'run `Unblock-File ` on it (the binaries are unsigned, so SmartScreen may block' - add 'them otherwise), extract both onto your PATH, then run `cortex --local` in one' - add 'terminal and `agentop observe` in another. `agentop service`, `setup`, `uninstall`' + add 'them otherwise), and extract both onto your PATH. Then, in a NEW terminal (an open one' + add 'keeps the old PATH), run `cortex --local`, and `agentop observe` in another. `agentop service`, `setup`, `uninstall`' add 'and `update` are not supported there yet. See docs/getting-started.md.' if gh release view "${TAG}" >/dev/null 2>&1; then # Uploading assets does not move the tag, so on a REUSED tag the release diff --git a/docs/getting-started.md b/docs/getting-started.md index 5292828a0..28222e169 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -34,9 +34,9 @@ When setup is done, open a new terminal. The new terminal reads the new `PATH`. 1. From the [releases page](https://github.com/rossoctl/cortex/releases), download `agentop__windows_amd64.zip` and `cortex__windows_amd64.zip` (`arm64` on an Arm PC), and `checksums.txt`. 2. Check them in PowerShell. `checksums.txt` has lower-case hashes, and `Get-FileHash` prints upper case, so compare `(Get-FileHash .\agentop__windows_amd64.zip -Algorithm SHA256).Hash.ToLower()` with the line for that file, and the same for `cortex`. 3. Unblock both: `Unblock-File .\agentop__windows_amd64.zip`, and the same for `cortex`. The binaries are not signed yet, and a downloaded `.zip` passes its "from the internet" mark on to what it holds, so without this SmartScreen may block them. -4. Unzip both into one folder, for example `$HOME\.local\bin`, and add that folder to your user `PATH`. -5. In one terminal, run the proxy: `cortex --local`. It writes `~/.cortex/config.yaml` on first run. Stop it with `Ctrl-C`. -6. In a second terminal, run `agentop observe`. +4. Unzip both into one folder, for example `$HOME\.local\bin`, and add that folder to your user `PATH`. Then open a new terminal: a terminal that is already open keeps the old `PATH`. +5. In that new terminal, run the proxy: `cortex --local`. It writes `~/.cortex/config.yaml` on first run. Stop it with `Ctrl-C`. If it says it can't parse `~/.cortex/config.yaml`, a file written by an earlier Windows build, delete that file and run it again: Cortex writes a fresh one. +6. In a second new terminal, run `agentop observe`. Then connect Claude Code with `agentop configure claude-code enable`, or run one session through Cortex with `agentop exec -- claude`.