Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Rename the tap's Vector mirror so the beacon dependency stops colliding

Claude18b1847fb60b
diff --git a/README.md b/README.md
index 55caf5de..2eb7a314 100644
--- a/README.md
+++ b/README.md
@@ -291,10 +291,13 @@ for rollout, validation, retention, and SIEM forwarding. For vendor review, see
### For Developers
-Install the released CLI with Homebrew, or build from source. The Homebrew formula
-depends on the tap's own `vector` formula (Vector is not in homebrew-core), so a Homebrew
-install can connect to Asymptote Managed without a second step; on Linux, install the `vector` package from [vector.dev](https://vector.dev)
-if you want managed forwarding.
+Install the released CLI with Homebrew, or build from source. On macOS the formula also
+pulls in the tap's own Vector mirror, so a Homebrew install can connect to Asymptote
+Managed without a second step. That mirror is the `beacon-vector` formula, not `vector`:
+Homebrew allows a single keg named `vector`, so it installs alongside — and never
+conflicts with — a Vector you already have from `vectordotdev/brew`. It is kept off your
+PATH and Beacon finds it on its own. On Linux, install the `vector` package from
+[vector.dev](https://vector.dev) if you want managed forwarding.
```bash
brew tap asymptote-labs/tap
diff --git a/beacon-release-validation-runbook.md b/beacon-release-validation-runbook.md
index 17de6cb2..59269505 100644
--- a/beacon-release-validation-runbook.md
+++ b/beacon-release-validation-runbook.md
@@ -111,7 +111,8 @@ Acceptance criteria:
## Managed Ingest Connect Smoke
Needs a browser signed in to the Asymptote dashboard as a member of an org with managed
-ingest enabled (Asymptote Test), and Vector on the machine (`brew install beacon` pulls it).
+ingest enabled (Asymptote Test), and Vector 0.50+ on the machine (`brew install beacon`
+pulls in the `beacon-vector` keg on macOS; otherwise the signed `.pkg` or vector.dev).
- [ ] `beacon endpoint connect --no-browser` prints an approval URL; approve it, and the
command ends with "Connected to Asymptote as device …" and a running forwarder.
diff --git a/cli/beacon/.goreleaser.yaml b/cli/beacon/.goreleaser.yaml
index 35b6bf5d..24955f88 100644
--- a/cli/beacon/.goreleaser.yaml
+++ b/cli/beacon/.goreleaser.yaml
@@ -222,10 +222,27 @@ brews:
# Vector runs the optional Asymptote managed forwarder (`beacon endpoint connect`);
# pulling it in here means a Homebrew install can connect without a second step.
# Vector is not in homebrew-core (it ships from vectordotdev/brew, and Homebrew no
- # longer taps third-party dependencies on its own), so the tap carries its own
- # Formula/vector.rb, mirrored from Vector's release tarballs, and depends on that.
+ # longer taps third-party dependencies on its own), so the tap mirrors Vector's
+ # release tarballs itself.
+ #
+ # The mirror is named `beacon-vector`, NOT `vector`, and that name is load-bearing.
+ # Homebrew allows exactly one keg named `vector` no matter which tap it came from,
+ # so depending on a tap formula by that name made `brew install/upgrade beacon` fail
+ # outright for everyone who already had Vector from vectordotdev/brew -- the upstream
+ # tap, and the one vector.dev points at:
+ # Error: vector is already installed from vectordotdev/brew!
+ # Please `brew uninstall vector` first.
+ # No spelling of a `vector` dependency can be satisfied by both taps. Under its own
+ # name the keg coexists with any other Vector, and it keeps its binary in libexec --
+ # which Homebrew never links into the prefix -- so it cannot collide on a bin/vector
+ # symlink either. FindVector looks there first; see internal/endpoint/asymptote.
+ #
+ # os: mac because the mirror only carries Vector's macOS tarballs; renders as
+ # `depends_on "..." if OS.mac?`. Homebrew-on-Linux installs Beacon with no
+ # dependency and uses the vector.dev package, as the docs say.
dependencies:
- - name: asymptote-labs/tap/vector
+ - name: asymptote-labs/tap/beacon-vector
+ os: mac
install: |
bin.install "beacon"
bin.install "beacon-hooks"
@@ -233,8 +250,12 @@ brews:
caveats: |
To configure local endpoint telemetry, run:
beacon endpoint install
+
To forward telemetry to the Asymptote dashboard (opt-in, revocable), run:
beacon endpoint connect
+ On macOS that needs no extra step: this formula installs its own Vector as
+ beacon-vector, kept out of PATH so it never collides with a Vector you
+ already have. On Linux, install Vector 0.50 or newer from https://vector.dev.
test: |
system "#{bin}/beacon", "version"
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index 80b925ab..ad64567a 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -513,8 +513,12 @@ stores the per-device key in a `0600` secrets file, and runs Vector as the
JSONL producer and Vector does the network. Only lines written after approval
are shipped, and revoking the device from the dashboard stops ingestion within
about a minute. Vector 0.50 or newer is required: `/opt/beacon/bin/vector` from
-the signed package, `vector` from Homebrew, or the Linux package from
-vector.dev.
+the signed package, the `beacon-vector` keg that `brew install beacon` pulls in on
+macOS, any other Vector 0.50+ already on the machine, or the Linux package from
+vector.dev. The Homebrew mirror is named `beacon-vector` rather than `vector`, and
+keeps its binary in `libexec`, because Homebrew allows a single keg named `vector`
+and a single `bin/vector` symlink: under its own name it installs alongside a Vector
+from `vectordotdev/brew` instead of refusing to install at all.
The same pack is available for running Vector by hand:
diff --git a/cli/beacon/goreleaser_brew_test.go b/cli/beacon/goreleaser_brew_test.go
new file mode 100644
index 00000000..7b5ffd06
--- /dev/null
+++ b/cli/beacon/goreleaser_brew_test.go
@@ -0,0 +1,102 @@
+package main
+
+import (
+ "os"
+ "path"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/asymptote"
+ "gopkg.in/yaml.v3"
+)
+
+// brewConfig is the slice of .goreleaser.yaml the Homebrew formula is generated from.
+type brewConfig struct {
+ Brews []struct {
+ Name string `yaml:"name"`
+ Dependencies []struct {
+ Name string `yaml:"name"`
+ OS string `yaml:"os"`
+ } `yaml:"dependencies"`
+ } `yaml:"brews"`
+}
+
+func loadBrewConfig(t *testing.T) brewConfig {
+ t.Helper()
+ raw, err := os.ReadFile(".goreleaser.yaml")
+ if err != nil {
+ t.Fatalf("read .goreleaser.yaml: %v", err)
+ }
+ var config brewConfig
+ if err := yaml.Unmarshal(raw, &config); err != nil {
+ t.Fatalf("parse .goreleaser.yaml: %v", err)
+ }
+ if len(config.Brews) == 0 {
+ t.Fatal("no brews entry in .goreleaser.yaml; the Homebrew formula is a release contract")
+ }
+ return config
+}
+
+// TestHomebrewFormulaNeverDependsOnAFormulaNamedVector pins the fix for a `brew upgrade
+// beacon` that failed outright:
+//
+// Error: vector is already installed from vectordotdev/brew!
+// Please `brew uninstall vector` first.
+//
+// Vector is not in homebrew-core, so the tap mirrors it, and the formula depends on that
+// mirror so a Homebrew install can run `beacon endpoint connect` without a second step.
+// The mirror must not be named `vector`: Homebrew allows exactly one keg by that name no
+// matter which tap it came from, so on every machine that already had Vector from
+// vectordotdev/brew -- the upstream tap, and the one vector.dev points at -- the dependency
+// was unsatisfiable and took the whole beacon install down with it. No spelling of a
+// `vector` dependency can be satisfied by both taps; only a different formula name can.
+func TestHomebrewFormulaNeverDependsOnAFormulaNamedVector(t *testing.T) {
+ for _, brew := range loadBrewConfig(t).Brews {
+ for _, dep := range brew.Dependencies {
+ // A tap-qualified dependency is owner/tap/formula, so the formula name is the
+ // last path element; a bare name has no separator and is its own last element.
+ if strings.EqualFold(path.Base(dep.Name), "vector") {
+ t.Errorf("brew %q depends on %q: Homebrew allows one keg named \"vector\", so this "+
+ "breaks installs for everyone who already has Vector from vectordotdev/brew. "+
+ "Depend on the tap's %q mirror instead.", brew.Name, dep.Name, asymptote.TapVectorFormula)
+ }
+ }
+ }
+}
+
+// TestHomebrewFormulaDependsOnTheVectorMirrorFindVectorLooksFor keeps the two halves of the
+// one-step install in sync. The formula pulls in the tap's Vector mirror, and FindVector has
+// to know the keg name to build the path it lives at -- Homebrew does not link libexec, so
+// nothing else finds it. Renaming the formula on either side alone leaves `brew install
+// beacon` installing a Vector that `beacon endpoint connect` cannot see.
+//
+// The dependency is macOS-only because the mirror only carries Vector's macOS tarballs.
+// Dropping that guard would break Homebrew-on-Linux installs of Beacon outright, which is
+// how the tap's macOS-only vector.rb behaved before the rename.
+func TestHomebrewFormulaDependsOnTheVectorMirrorFindVectorLooksFor(t *testing.T) {
+ want := "asymptote-labs/tap/" + asymptote.TapVectorFormula
+ for _, brew := range loadBrewConfig(t).Brews {
+ if brew.Name != "beacon" {
+ continue
+ }
+ var found bool
+ for _, dep := range brew.Dependencies {
+ if dep.Name != want {
+ continue
+ }
+ found = true
+ if dep.OS != "mac" {
+ t.Errorf("brew %q depends on %q with os %q, want %q: the mirror carries only "+
+ "Vector's macOS tarballs, so an unguarded dependency breaks Homebrew-on-Linux "+
+ "installs of Beacon", brew.Name, dep.Name, dep.OS, "mac")
+ }
+ }
+ if !found {
+ t.Errorf("brew %q does not depend on %q; FindVector looks for that keg by name, so "+
+ "`beacon endpoint connect` would not find a Vector installed under another one",
+ brew.Name, want)
+ }
+ return
+ }
+ t.Fatal(`no brews entry named "beacon" in .goreleaser.yaml`)
+}
diff --git a/cli/beacon/internal/endpoint/asymptote/vector.go b/cli/beacon/internal/endpoint/asymptote/vector.go
index c559ad54..e27d1485 100644
--- a/cli/beacon/internal/endpoint/asymptote/vector.go
+++ b/cli/beacon/internal/endpoint/asymptote/vector.go
@@ -22,6 +22,17 @@ const VectorBinEnv = "BEACON_VECTOR_BIN"
// PackagedVectorPath is where the signed macOS package installs Vector.
const PackagedVectorPath = "/opt/beacon/bin/vector"
+// TapVectorFormula is the Homebrew formula the tap mirrors Vector as, and the name of the
+// keg `brew install beacon` pulls in on macOS.
+//
+// It is deliberately not "vector". Homebrew allows exactly one keg named `vector` no matter
+// which tap it came from, so a tap formula by that name made `brew install/upgrade beacon`
+// fail outright for anyone who already had Vector from vectordotdev/brew. Under its own name
+// the keg coexists with any other Vector, and it keeps its binary in libexec -- which
+// Homebrew never links into the prefix -- so it also cannot collide on a bin/vector symlink.
+// That is why it is only ever found by path, never through PATH.
+const TapVectorFormula = "beacon-vector"
+
// VectorInfo describes the Vector binary connect will run.
type VectorInfo struct {
Path string `json:"path"`
@@ -29,7 +40,13 @@ type VectorInfo struct {
}
// ErrVectorNotFound is returned when no usable Vector binary exists.
-var ErrVectorNotFound = errors.New("vector was not found; install it from https://vector.dev (Homebrew: brew install vector) or set " + VectorBinEnv)
+//
+// The Homebrew hint names the tap's own formula rather than a bare "brew install vector":
+// Vector is not in homebrew-core, so the bare name is ambiguous once both vectordotdev/brew
+// and asymptote-labs/tap are tapped, and Homebrew refuses an ambiguous name. Any Vector at
+// or above MinVectorVersion satisfies FindVector, whichever tap or package it came from.
+var ErrVectorNotFound = errors.New("vector was not found; install it from https://vector.dev " +
+ "(macOS: brew install asymptote-labs/tap/" + TapVectorFormula + ") or set " + VectorBinEnv)
// runCommandOutput is swapped by tests to fake `vector --version`.
var runCommandOutput = func(bin string, args ...string) ([]byte, error) {
@@ -45,9 +62,12 @@ var (
// FindVector locates a Vector binary of at least MinVectorVersion.
//
// Order: the explicit argument, BEACON_VECTOR_BIN, the packaged /opt/beacon/bin/vector, the
-// Homebrew prefixes, then PATH. The first candidate that exists is checked for version; a too-old
-// binary is an error rather than a reason to keep searching, because silently running a
-// different Vector than the one the operator pointed at would be worse.
+// beacon-vector keg in each Homebrew prefix, a linked vector in each Homebrew prefix, then
+// PATH. The first candidate that exists is checked for version; a too-old binary is an error
+// rather than a reason to keep searching, because silently running a different Vector than the
+// one the operator pointed at would be worse. That is also why the beacon-vector keg is tried
+// ahead of any other Homebrew Vector: it is the copy whose version the tap pins, so it cannot
+// be the one that turns a working install into a version error.
func FindVector(explicit string) (VectorInfo, error) {
for _, candidate := range vectorCandidates(explicit) {
if candidate == "" {
@@ -82,12 +102,46 @@ var vectorSearchPaths = defaultVectorSearchPaths
func defaultVectorSearchPaths() []string {
paths := []string{PackagedVectorPath}
- if runtime.GOOS == "darwin" {
- paths = append(paths, "/opt/homebrew/bin/vector", "/usr/local/bin/vector")
+ prefixes := homebrewPrefixes()
+ // Every beacon-vector keg first, then every linked vector. Interleaving the two per
+ // prefix would let an old linked Vector in the first prefix mask the pinned keg in the
+ // second, and FindVector treats a too-old binary as an error rather than moving on.
+ for _, prefix := range prefixes {
+ paths = append(paths, filepath.Join(prefix, "opt", TapVectorFormula, "libexec", "vector"))
+ }
+ for _, prefix := range prefixes {
+ paths = append(paths, filepath.Join(prefix, "bin", "vector"))
}
return paths
}
+// homebrewPrefixes lists the Homebrew prefixes to look under, HOMEBREW_PREFIX first when the
+// caller set one. The defaults are the per-platform standard prefixes: Apple Silicon and Intel
+// macOS, and the Linuxbrew prefix. A prefix that does not exist just yields candidates that
+// fail the stat in FindVector.
+func homebrewPrefixes() []string {
+ var prefixes []string
+ if prefix := strings.TrimSpace(os.Getenv("HOMEBREW_PREFIX")); prefix != "" {
+ prefixes = append(prefixes, prefix)
+ }
+ switch runtime.GOOS {
+ case "darwin":
+ prefixes = append(prefixes, "/opt/homebrew", "/usr/local")
+ case "linux":
+ prefixes = append(prefixes, "/home/linuxbrew/.linuxbrew")
+ }
+ seen := make(map[string]bool, len(prefixes))
+ unique := prefixes[:0]
+ for _, prefix := range prefixes {
+ if seen[prefix] {
+ continue
+ }
+ seen[prefix] = true
+ unique = append(unique, prefix)
+ }
+ return unique
+}
+
func vectorCandidates(explicit string) []string {
candidates := []string{explicit, os.Getenv(VectorBinEnv)}
candidates = append(candidates, vectorSearchPaths()...)
diff --git a/cli/beacon/internal/endpoint/asymptote/vector_test.go b/cli/beacon/internal/endpoint/asymptote/vector_test.go
index 5e15b182..119aad50 100644
--- a/cli/beacon/internal/endpoint/asymptote/vector_test.go
+++ b/cli/beacon/internal/endpoint/asymptote/vector_test.go
@@ -4,6 +4,7 @@ import (
"errors"
"os"
"path/filepath"
+ "slices"
"strings"
"testing"
)
@@ -115,3 +116,62 @@ func TestEnrollmentStoreUsesPrivatePermissionsAndAtomicWrites(t *testing.T) {
t.Fatal("RemoveState should delete the directory")
}
}
+
+// TestDefaultVectorSearchPathsPrefersTheBeaconVectorKeg pins where a Homebrew-installed
+// Vector is looked for. The tap mirrors Vector as the beacon-vector keg rather than as a
+// formula named `vector`, because Homebrew allows one keg by that name and a `vector`
+// dependency broke `brew upgrade beacon` for anyone already running vectordotdev/brew's.
+// That keg keeps its binary in libexec, which Homebrew never links, so nothing finds it
+// except this path -- and it is tried ahead of any linked vector because it is the copy
+// whose version the tap pins, and FindVector treats a too-old binary as an error rather
+// than a reason to keep looking.
+func TestDefaultVectorSearchPathsPrefersTheBeaconVectorKeg(t *testing.T) {
+ t.Setenv("HOMEBREW_PREFIX", filepath.Join("/fake", "brew"))
+ paths := defaultVectorSearchPaths()
+
+ if len(paths) == 0 || paths[0] != PackagedVectorPath {
+ t.Fatalf("defaultVectorSearchPaths() = %q, want the packaged Vector first", paths)
+ }
+ keg := filepath.Join("/fake", "brew", "opt", TapVectorFormula, "libexec", "vector")
+ if !slices.Contains(paths, keg) {
+ t.Fatalf("defaultVectorSearchPaths() = %q, want it to include the beacon-vector keg %q", paths, keg)
+ }
+ if linked := filepath.Join("/fake", "brew", "bin", "vector"); !slices.Contains(paths, linked) {
+ t.Fatalf("defaultVectorSearchPaths() = %q, want it to include a linked Vector %q", paths, linked)
+ }
+
+ lastKeg, firstLinked := -1, len(paths)
+ for i, path := range paths {
+ switch {
+ case strings.Contains(path, filepath.Join("opt", TapVectorFormula)):
+ lastKeg = i
+ case path != PackagedVectorPath && strings.HasSuffix(path, filepath.Join("bin", "vector")):
+ firstLinked = min(firstLinked, i)
+ }
+ }
+ if lastKeg > firstLinked {
+ t.Errorf("defaultVectorSearchPaths() = %q, want every beacon-vector keg before every linked Vector; "+
+ "interleaving lets an old linked Vector in one prefix mask the pinned keg in the next", paths)
+ }
+}
+
+// TestHomebrewPrefixesDeduplicates covers HOMEBREW_PREFIX being set to the platform default,
+// which would otherwise search the same prefix twice.
+func TestHomebrewPrefixesDeduplicates(t *testing.T) {
+ prefixes := homebrewPrefixes()
+ if len(prefixes) == 0 {
+ t.Skip("no Homebrew prefixes on this platform")
+ }
+ t.Setenv("HOMEBREW_PREFIX", prefixes[0])
+ got := homebrewPrefixes()
+ seen := make(map[string]bool, len(got))
+ for _, prefix := range got {
+ if seen[prefix] {
+ t.Fatalf("homebrewPrefixes() = %q, want no duplicates", got)
+ }
+ seen[prefix] = true
+ }
+ if len(got) != len(prefixes) {
+ t.Errorf("homebrewPrefixes() = %q, want the same %d prefixes as the unset default %q", got, len(prefixes), prefixes)
+ }
+}
diff --git a/docs/cli/endpoint-connect.mdx b/docs/cli/endpoint-connect.mdx
index db053949..5de1616b 100644
--- a/docs/cli/endpoint-connect.mdx
+++ b/docs/cli/endpoint-connect.mdx
@@ -17,12 +17,12 @@ beacon endpoint disconnect [flags]
## Prerequisites
- Beacon endpoint installed (`beacon endpoint install`) and writing local JSONL.
-- Vector 0.50 or newer on the machine (Apple Silicon gets 0.58 from Homebrew or the package; Intel Macs get 0.50.0, the last x86_64 build Vector published). The signed macOS package installs it at `/opt/beacon/bin/vector`; Homebrew installs it with Beacon (the `asymptote-labs/tap/beacon` formula depends on the tap's own `vector` formula, since Vector is not in homebrew-core); on Linux install the `vector` package from [vector.dev](https://vector.dev). `connect` stops before opening a browser if no usable Vector is found.
+- Vector 0.50 or newer on the machine (Apple Silicon gets 0.58 from Homebrew or the package; Intel Macs get 0.50.0, the last x86_64 build Vector published). The signed macOS package installs it at `/opt/beacon/bin/vector`; on macOS Homebrew installs it with Beacon, as the tap's `beacon-vector` keg (named that rather than `vector` so it coexists with a Vector from `vectordotdev/brew`, and kept in `libexec` so it stays off your PATH); on Linux install the `vector` package from [vector.dev](https://vector.dev). `connect` stops before opening a browser if no usable Vector is found.
- A browser where you can sign in to the Asymptote dashboard as a member of an organization that has managed ingest enabled.
## What connect does
-1. Locates Vector: `--vector-bin`, then `BEACON_VECTOR_BIN`, then `/opt/beacon/bin/vector`, the Homebrew prefixes, then `PATH`.
+1. Locates Vector: `--vector-bin`, then `BEACON_VECTOR_BIN`, then `/opt/beacon/bin/vector`, the `beacon-vector` keg in each Homebrew prefix, a linked `vector` in each Homebrew prefix, then `PATH`. The `beacon-vector` keg is tried ahead of any other Homebrew Vector because it is the copy the tap pins at a supported version.
2. Registers this machine's hostname, operating system, architecture, Beacon version and install mode with the dashboard, and opens `/cli/enroll` in your browser. The approval page shows those details; nothing is minted until someone clicks **Approve this device**.
3. Receives the device key through a loopback callback and a PKCE exchange. The key is written once to `asymptote/vector-secrets.json` with mode `0600` and is never printed.
4. Renders `asymptote/vector.toml` from the [Asymptote pack](/cli/asymptote) template with the ingest URL returned by enrollment, runs `vector validate`, installs a service unit and starts it.
diff --git a/docs/cli/install.mdx b/docs/cli/install.mdx
index 4f05e4e8..4e622807 100644
--- a/docs/cli/install.mdx
+++ b/docs/cli/install.mdx
@@ -26,7 +26,9 @@ brew install beacon
beacon version
```
-The formula depends on the tap's own `vector` formula (`asymptote-labs/tap/vector`, mirrored from Vector's releases because Vector is not in homebrew-core), which runs the optional [Asymptote Managed forwarder](/cli/endpoint-connect); Homebrew installs it alongside Beacon.
+On macOS the formula also depends on `asymptote-labs/tap/beacon-vector`, the tap's mirror of Vector's releases (Vector is not in homebrew-core), which runs the optional [Asymptote Managed forwarder](/cli/endpoint-connect); Homebrew installs it alongside Beacon so no second step is needed.
+
+The mirror is named `beacon-vector` rather than `vector` on purpose. Homebrew allows exactly one keg named `vector` no matter which tap it came from, so a mirror by that name could not be installed at all on a machine that already had Vector from `vectordotdev/brew`. Under its own name it coexists with any Vector you already run, and because it keeps its binary in `libexec` — which Homebrew never links — it stays off your PATH and never shadows one. Beacon finds it by path; you do not need to configure anything.
<Accordion title="Example output">
```bash title="beacon version output"