Skip to content

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

Fix codex detector

Justin D'Souza570efe013370
diff --git a/README.md b/README.md
index 2f668717..9c4285b9 100644
--- a/README.md
+++ b/README.md
@@ -113,19 +113,21 @@ make build
### Install Locally
```bash
-beacon endpoint install
+beacon endpoint install --collector /path/to/beacon-otelcol
beacon endpoint status
```
The normal CLI flow uses per-user endpoint paths by default. Cursor hooks,
Claude Code OTLP, and Codex OTLP all write to the same user runtime log:
`~/.beacon/endpoint/logs/runtime.jsonl`. Use `--system` only for root-managed
-package or MDM deployments.
+package or MDM deployments. The endpoint collector config requires Beacon's
+custom `beacon-otelcol` binary, which is provided by the macOS package; CLI-only
+installs must put `beacon-otelcol` on `PATH` or pass `--collector`.
### Set Content Retention
```bash
-beacon endpoint install --content-retention metadata
+beacon endpoint install --collector /path/to/beacon-otelcol --content-retention metadata
```
### Configure Wazuh Output
@@ -217,7 +219,7 @@ Common commands:
```bash
beacon version
-beacon endpoint install
+beacon endpoint install --collector /path/to/beacon-otelcol
beacon endpoint status
beacon endpoint discover
beacon endpoint dashboard --open
@@ -265,15 +267,15 @@ installs the CLI, collector, Wazuh content pack, and deployment scripts. The
package should apply explicit system endpoint settings, for example:
```bash
-beacon endpoint install --system --harness claude,codex --content-retention metadata
+beacon endpoint install --system --collector /opt/beacon/bin/beacon-otelcol --harness claude,codex --content-retention metadata
```
Before publishing a release, verify the build from a clean checkout and clean
macOS host or VM:
- `beacon version` reports the expected version, commit, and build date.
-- `beacon endpoint install --no-start` succeeds without developer
- tooling.
+- `beacon endpoint install --collector /path/to/beacon-otelcol --no-start`
+ succeeds without developer tooling.
- `beacon endpoint status` reports config, collector, service, harness,
diagnostic, and runtime log paths.
- `beacon endpoint wazuh validate` writes a valid Beacon JSONL event.
diff --git a/cli/beacon-hooks/internal/config/config.go b/cli/beacon-hooks/internal/config/config.go
index cec14faa..aa48bd74 100644
--- a/cli/beacon-hooks/internal/config/config.go
+++ b/cli/beacon-hooks/internal/config/config.go
@@ -29,6 +29,8 @@ const (
ContentRetentionFull ContentRetention = "full"
)
+var SystemEndpointConfigPath = "/Library/Application Support/Beacon/Endpoint/config.json"
+
// Scannable extensions
var scannableExtensions = map[string]bool{
// JavaScript/TypeScript
@@ -134,22 +136,48 @@ func EnsureStateDir(platform string) error {
}
func ContentRetentionMode() ContentRetention {
- endpointPath := filepath.Join(BeaconDir, "endpoint", "config.json")
- data, err := os.ReadFile(endpointPath)
- if err != nil {
- return ContentRetentionMetadata
+ if mode, ok := parseContentRetention(os.Getenv("BEACON_CONTENT_RETENTION")); ok {
+ return mode
+ }
+ for _, endpointPath := range endpointConfigPaths() {
+ data, err := os.ReadFile(endpointPath)
+ if err != nil {
+ continue
+ }
+ var cfg map[string]interface{}
+ if err := json.Unmarshal(data, &cfg); err != nil {
+ continue
+ }
+ if mode, ok := parseContentRetention(cfg["content_retention"]); ok {
+ return mode
+ }
+ }
+ return ContentRetentionMetadata
+}
+
+func endpointConfigPaths() []string {
+ if endpointPath := os.Getenv("BEACON_ENDPOINT_CONFIG"); endpointPath != "" {
+ return []string{endpointPath}
}
- var cfg map[string]interface{}
- if err := json.Unmarshal(data, &cfg); err != nil {
- return ContentRetentionMetadata
+ userPath := filepath.Join(BeaconDir, "endpoint", "config.json")
+ if usesSystemEndpointLog(os.Getenv("BEACON_ENDPOINT_LOG")) {
+ return []string{SystemEndpointConfigPath, userPath}
}
- mode, _ := cfg["content_retention"].(string)
+ return []string{userPath, SystemEndpointConfigPath}
+}
+
+func usesSystemEndpointLog(path string) bool {
+ return strings.HasPrefix(path, "/var/log/") || strings.HasPrefix(path, "/Library/")
+}
+
+func parseContentRetention(value interface{}) (ContentRetention, bool) {
+ mode, _ := value.(string)
switch ContentRetention(mode) {
case ContentRetentionRedacted:
- return ContentRetentionRedacted
+ return ContentRetentionRedacted, true
case ContentRetentionFull:
- return ContentRetentionFull
+ return ContentRetentionFull, true
default:
- return ContentRetentionMetadata
+ return ContentRetentionMetadata, false
}
}
diff --git a/cli/beacon-hooks/internal/config/config_test.go b/cli/beacon-hooks/internal/config/config_test.go
index 8ae68e0d..d9c35234 100644
--- a/cli/beacon-hooks/internal/config/config_test.go
+++ b/cli/beacon-hooks/internal/config/config_test.go
@@ -1,6 +1,7 @@
package config
import (
+ "os"
"path/filepath"
"testing"
)
@@ -104,3 +105,57 @@ func TestCursorDirPath(t *testing.T) {
t.Errorf("CursorDir parent should be '.beacon', got %q", filepath.Dir(CursorDir))
}
}
+
+func TestContentRetentionModeReadsExplicitEndpointConfig(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "config.json")
+ if err := os.WriteFile(path, []byte(`{"content_retention":"full"}`), 0644); err != nil {
+ t.Fatalf("write endpoint config: %v", err)
+ }
+ t.Setenv("BEACON_ENDPOINT_CONFIG", path)
+
+ if got := ContentRetentionMode(); got != ContentRetentionFull {
+ t.Fatalf("ContentRetentionMode() = %q, want %q", got, ContentRetentionFull)
+ }
+}
+
+func TestContentRetentionModePrefersSystemConfigForSystemLog(t *testing.T) {
+ home := t.TempDir()
+ oldBeaconDir := BeaconDir
+ oldSystemPath := SystemEndpointConfigPath
+ BeaconDir = filepath.Join(home, ".beacon")
+ SystemEndpointConfigPath = filepath.Join(t.TempDir(), "system-config.json")
+ t.Cleanup(func() {
+ BeaconDir = oldBeaconDir
+ SystemEndpointConfigPath = oldSystemPath
+ })
+ userPath := filepath.Join(BeaconDir, "endpoint", "config.json")
+ if err := os.MkdirAll(filepath.Dir(userPath), 0755); err != nil {
+ t.Fatalf("mkdir user endpoint config dir: %v", err)
+ }
+ if err := os.WriteFile(userPath, []byte(`{"content_retention":"metadata"}`), 0644); err != nil {
+ t.Fatalf("write user endpoint config: %v", err)
+ }
+ if err := os.WriteFile(SystemEndpointConfigPath, []byte(`{"content_retention":"full"}`), 0644); err != nil {
+ t.Fatalf("write system endpoint config: %v", err)
+ }
+ t.Setenv("BEACON_ENDPOINT_LOG", "/var/log/beacon-agent/runtime.jsonl")
+
+ if got := ContentRetentionMode(); got != ContentRetentionFull {
+ t.Fatalf("ContentRetentionMode() = %q, want %q", got, ContentRetentionFull)
+ }
+}
+
+func TestContentRetentionModeDefaultsToMetadata(t *testing.T) {
+ oldBeaconDir := BeaconDir
+ oldSystemPath := SystemEndpointConfigPath
+ BeaconDir = filepath.Join(t.TempDir(), ".beacon")
+ SystemEndpointConfigPath = filepath.Join(t.TempDir(), "missing-config.json")
+ t.Cleanup(func() {
+ BeaconDir = oldBeaconDir
+ SystemEndpointConfigPath = oldSystemPath
+ })
+
+ if got := ContentRetentionMode(); got != ContentRetentionMetadata {
+ t.Fatalf("ContentRetentionMode() = %q, want %q", got, ContentRetentionMetadata)
+ }
+}
diff --git a/cli/beacon/.goreleaser.yaml b/cli/beacon/.goreleaser.yaml
index 4282d4e6..d2386d28 100644
--- a/cli/beacon/.goreleaser.yaml
+++ b/cli/beacon/.goreleaser.yaml
@@ -84,8 +84,10 @@ brews:
install: |
bin.install "beacon"
caveats: |
- To configure local endpoint telemetry, run:
- beacon endpoint install
+ The Homebrew formula installs the beacon CLI only. Endpoint telemetry also
+ requires the custom beacon-otelcol collector; install the macOS package
+ that includes it, place beacon-otelcol on PATH, or pass:
+ beacon endpoint install --collector /path/to/beacon-otelcol
test: |
system "#{bin}/beacon", "version"
@@ -110,7 +112,8 @@ release:
## Quick Start
```bash
- beacon endpoint install
+ # Endpoint telemetry requires the custom beacon-otelcol collector.
+ beacon endpoint install --collector /path/to/beacon-otelcol
beacon endpoint status
beacon endpoint wazuh print-config
```
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index ab063bab..f4faf0af 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -11,7 +11,7 @@ make build
## Common Commands
```bash
-./beacon endpoint install
+./beacon endpoint install --collector /path/to/beacon-otelcol
./beacon endpoint status --json
./beacon endpoint discover --json
./beacon endpoint repair
@@ -21,7 +21,8 @@ make build
Endpoint commands use per-user paths by default so hook and OTLP telemetry share
`~/.beacon/endpoint/logs/runtime.jsonl`. Use `--system` for root-managed
-deployment paths.
+deployment paths. Endpoint install requires Beacon's custom `beacon-otelcol`
+collector, provided by the macOS package or passed with `--collector`.
## Dashboard
diff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.go
index fd71ce31..0ee64077 100644
--- a/cli/beacon/cmd/endpoint.go
+++ b/cli/beacon/cmd/endpoint.go
@@ -255,7 +255,7 @@ func init() {
endpointInstallCmd.Flags().StringVar(&endpointOpts.harnesses, "harness", "claude,codex", "Comma-separated harnesses to configure")
endpointInstallCmd.Flags().IntVar(&endpointOpts.grpcPort, "otlp-grpc-port", endpointconfig.DefaultGRPCPort, "Local OTLP gRPC port")
endpointInstallCmd.Flags().IntVar(&endpointOpts.httpPort, "otlp-http-port", endpointconfig.DefaultHTTPPort, "Local OTLP HTTP port")
- endpointInstallCmd.Flags().StringVar(&endpointOpts.collectorPath, "collector", "", "Path to an otelcol or otelcol-contrib binary")
+ endpointInstallCmd.Flags().StringVar(&endpointOpts.collectorPath, "collector", "", "Path to a beacon-otelcol binary")
endpointInstallCmd.Flags().BoolVar(&endpointOpts.noStart, "no-start", false, "Write files without starting the launchd service")
endpointInstallCmd.Flags().StringVar(&endpointOpts.contentRetention, "content-retention", "metadata", "Content retention mode: metadata, redacted, or full")
endpointRepairCmd.Flags().StringVar(&endpointOpts.harnesses, "harness", "claude,codex", "Comma-separated harnesses to configure")
diff --git a/cli/beacon/internal/embedded/hooks.bin b/cli/beacon/internal/embedded/hooks.bin
old mode 100644
new mode 100755
index 61e04996..222255a3
Binary files a/cli/beacon/internal/embedded/hooks.bin and b/cli/beacon/internal/embedded/hooks.bin differ
diff --git a/cli/beacon/internal/endpoint/collector/collector.go b/cli/beacon/internal/endpoint/collector/collector.go
index 795d03a5..9b739897 100644
--- a/cli/beacon/internal/endpoint/collector/collector.go
+++ b/cli/beacon/internal/endpoint/collector/collector.go
@@ -10,6 +10,17 @@ import (
endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
)
+const (
+ BinaryName = "beacon-otelcol"
+ PackagedBinaryPath = "/opt/beacon/bin/beacon-otelcol"
+)
+
+var (
+ lookPath = exec.LookPath
+ currentExecutable = os.Executable
+ discoverDefaultBinaryCandidates = defaultBinaryCandidates
+)
+
type Status struct {
BinaryPath string `json:"binary_path,omitempty"`
ConfigPath string `json:"config_path,omitempty"`
@@ -20,21 +31,58 @@ type Status struct {
Message string `json:"message,omitempty"`
}
+func ResolveBinary(configured string) (string, error) {
+ if configured != "" {
+ if err := validateExecutable(configured); err != nil {
+ return "", fmt.Errorf("collector binary %q is not usable: %w", configured, err)
+ }
+ return configured, nil
+ }
+ if path := DiscoverBinary(""); path != "" {
+ return path, nil
+ }
+ return "", fmt.Errorf("beacon endpoint install requires the Beacon OpenTelemetry Collector (%s); install the macOS package that includes %s, ensure %s is on PATH, or pass --collector /path/to/%s", BinaryName, PackagedBinaryPath, BinaryName, BinaryName)
+}
+
func DiscoverBinary(configured string) string {
if configured != "" {
- if _, err := os.Stat(configured); err == nil {
+ if err := validateExecutable(configured); err == nil {
return configured
}
}
- if path, err := exec.LookPath("otelcol-contrib"); err == nil {
+ if path, err := lookPath(BinaryName); err == nil && validateExecutable(path) == nil {
return path
}
- if path, err := exec.LookPath("otelcol"); err == nil {
- return path
+ for _, path := range discoverDefaultBinaryCandidates() {
+ if err := validateExecutable(path); err == nil {
+ return path
+ }
}
return ""
}
+func defaultBinaryCandidates() []string {
+ paths := []string{PackagedBinaryPath}
+ if executable, err := currentExecutable(); err == nil {
+ paths = append([]string{filepath.Join(filepath.Dir(executable), BinaryName)}, paths...)
+ }
+ return paths
+}
+
+func validateExecutable(path string) error {
+ info, err := os.Stat(path)
+ if err != nil {
+ return err
+ }
+ if info.IsDir() {
+ return fmt.Errorf("is a directory")
+ }
+ if info.Mode().Perm()&0111 == 0 {
+ return fmt.Errorf("is not executable")
+ }
+ return nil
+}
+
func WriteConfig(cfg endpointconfig.Config) error {
if err := os.MkdirAll(filepath.Dir(cfg.Collector.ConfigPath), 0755); err != nil {
return err
@@ -134,7 +182,7 @@ func portOpen(port int) bool {
func LaunchAgentPlist(cfg endpointconfig.Config) string {
binary := DiscoverBinary(cfg.Collector.BinaryPath)
if binary == "" {
- binary = "otelcol"
+ binary = BinaryName
}
label := "com.beacon.endpoint.collector"
if cfg.UserMode {
diff --git a/cli/beacon/internal/endpoint/collector/collector_test.go b/cli/beacon/internal/endpoint/collector/collector_test.go
index 2f81f201..fbed89b2 100644
--- a/cli/beacon/internal/endpoint/collector/collector_test.go
+++ b/cli/beacon/internal/endpoint/collector/collector_test.go
@@ -1,8 +1,10 @@
package collector
import (
+ "errors"
"net"
"os"
+ "os/exec"
"path/filepath"
"runtime"
"strings"
@@ -64,7 +66,7 @@ func TestWriteConfigCreatesConfigAndSpoolDirectory(t *testing.T) {
}
func TestDiscoverBinaryPrefersConfiguredExistingPath(t *testing.T) {
- bin := filepath.Join(t.TempDir(), "collector")
+ bin := filepath.Join(t.TempDir(), BinaryName)
if err := os.WriteFile(bin, []byte("#!/bin/sh\n"), 0755); err != nil {
t.Fatalf("write fake collector: %v", err)
}
@@ -74,6 +76,64 @@ func TestDiscoverBinaryPrefersConfiguredExistingPath(t *testing.T) {
}
}
+func TestResolveBinaryRejectsMissingConfiguredPath(t *testing.T) {
+ missing := filepath.Join(t.TempDir(), BinaryName)
+
+ _, err := ResolveBinary(missing)
+ if err == nil || !strings.Contains(err.Error(), "not usable") || !strings.Contains(err.Error(), missing) {
+ t.Fatalf("ResolveBinary error = %v, want configured path error", err)
+ }
+}
+
+func TestDiscoverBinaryFindsBeaconOtelcolOnPath(t *testing.T) {
+ dir := t.TempDir()
+ bin := filepath.Join(dir, BinaryName)
+ if err := os.WriteFile(bin, []byte("#!/bin/sh\n"), 0755); err != nil {
+ t.Fatalf("write fake collector: %v", err)
+ }
+ t.Setenv("PATH", dir)
+ withCollectorDiscovery(t, nil, nil)
+
+ if got := DiscoverBinary(""); got != bin {
+ t.Fatalf("DiscoverBinary = %q, want PATH binary %q", got, bin)
+ }
+}
+
+func TestDiscoverBinaryIgnoresGenericOtelcol(t *testing.T) {
+ dir := t.TempDir()
+ generic := filepath.Join(dir, "otelcol-contrib")
+ if err := os.WriteFile(generic, []byte("#!/bin/sh\n"), 0755); err != nil {
+ t.Fatalf("write generic collector: %v", err)
+ }
+ t.Setenv("PATH", dir)
+ withCollectorDiscovery(t, nil, nil)
+
+ if got := DiscoverBinary(""); got != "" {
+ t.Fatalf("DiscoverBinary = %q, want empty for generic collector", got)
+ }
+}
+
+func TestDiscoverBinaryFindsAdjacentBeaconOtelcol(t *testing.T) {
+ dir := t.TempDir()
+ beacon := filepath.Join(dir, "beacon")
+ collector := filepath.Join(dir, BinaryName)
+ if err := os.WriteFile(collector, []byte("#!/bin/sh\n"), 0755); err != nil {
+ t.Fatalf("write adjacent collector: %v", err)
+ }
+ withCollectorDiscovery(t, func(file string) (string, error) {
+ if file == BinaryName {
+ return "", errors.New("not found")
+ }
+ return "", errors.New("unexpected lookup")
+ }, func() []string {
+ return []string{filepath.Join(filepath.Dir(beacon), BinaryName)}
+ })
+
+ if got := DiscoverBinary(""); got != collector {
+ t.Fatalf("DiscoverBinary = %q, want adjacent collector %q", got, collector)
+ }
+}
+
func TestPortAvailabilityAndOpenChecks(t *testing.T) {
ln, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
@@ -94,12 +154,15 @@ func TestLaunchAgentPlistUsesFallbackBinaryAndUserLabel(t *testing.T) {
cfg := testConfig(t)
cfg.UserMode = true
cfg.Collector.BinaryPath = filepath.Join(t.TempDir(), "missing-otelcol")
+ withCollectorDiscovery(t, func(file string) (string, error) {
+ return "", errors.New("not found")
+ }, nil)
plist := LaunchAgentPlist(cfg)
for _, want := range []string{
"<string>com.beacon.endpoint.collector.user</string>",
- "<string>otelcol</string>",
+ "<string>beacon-otelcol</string>",
"<string>--config</string>",
"<string>" + cfg.Collector.ConfigPath + "</string>",
} {
@@ -126,3 +189,25 @@ func TestWriteLaunchPlistUserMode(t *testing.T) {
t.Fatalf("plist path = %q, want %q", got, want)
}
}
+
+func withCollectorDiscovery(t *testing.T, lookup func(string) (string, error), candidates func() []string) {
+ t.Helper()
+ oldLookPath := lookPath
+ oldCandidates := discoverDefaultBinaryCandidates
+ if lookup == nil {
+ lookup = execLookPath
+ }
+ if candidates == nil {
+ candidates = func() []string { return nil }
+ }
+ lookPath = lookup
+ discoverDefaultBinaryCandidates = candidates
+ t.Cleanup(func() {
+ lookPath = oldLookPath
+ discoverDefaultBinaryCandidates = oldCandidates
+ })
+}
+
+func execLookPath(file string) (string, error) {
+ return exec.LookPath(file)
+}
diff --git a/cli/beacon/internal/endpoint/harness/harness.go b/cli/beacon/internal/endpoint/harness/harness.go
index 4f9023d8..ceb743e6 100644
--- a/cli/beacon/internal/endpoint/harness/harness.go
+++ b/cli/beacon/internal/endpoint/harness/harness.go
@@ -101,9 +101,6 @@ func DiscoverCodex() Harness {
h.TelemetryStatus = TelemetryMissing
h.Message = "Codex config file was not found"
}
- if !h.Detected && dirExists(filepath.Join(home, ".codex")) {
- h.Detected = true
- }
return h
}
diff --git a/cli/beacon/internal/endpoint/harness/harness_test.go b/cli/beacon/internal/endpoint/harness/harness_test.go
index c846c7d1..730a3903 100644
--- a/cli/beacon/internal/endpoint/harness/harness_test.go
+++ b/cli/beacon/internal/endpoint/harness/harness_test.go
@@ -156,6 +156,49 @@ func TestConfigureCodexWritesTelemetryBlockAndBackup(t *testing.T) {
}
}
+func TestDiscoverCodexDoesNotDetectConfigDirectoryOnly(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ binDir := t.TempDir()
+ t.Setenv("PATH", binDir)
+ if err := os.MkdirAll(filepath.Join(home, ".codex"), 0755); err != nil {
+ t.Fatalf("mkdir codex config dir: %v", err)
+ }
+
+ h := DiscoverCodex()
+ if h.Detected {
+ t.Fatalf("DiscoverCodex detected Codex from config directory only: %#v", h)
+ }
+ if h.ConfigPath != filepath.Join(home, ".codex", "config.toml") {
+ t.Fatalf("ConfigPath = %q, want home config path", h.ConfigPath)
+ }
+ if h.TelemetryStatus != TelemetryMissing {
+ t.Fatalf("TelemetryStatus = %q, want %q", h.TelemetryStatus, TelemetryMissing)
+ }
+}
+
+func TestDiscoverCodexDetectsExecutableOnPath(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ binDir := t.TempDir()
+ t.Setenv("PATH", binDir)
+ codexPath := filepath.Join(binDir, "codex")
+ if err := os.WriteFile(codexPath, []byte("#!/bin/sh\necho codex 1.2.3\n"), 0755); err != nil {
+ t.Fatalf("write fake codex executable: %v", err)
+ }
+
+ h := DiscoverCodex()
+ if !h.Detected {
+ t.Fatalf("DiscoverCodex did not detect executable on PATH: %#v", h)
+ }
+ if h.ExecutablePath != codexPath {
+ t.Fatalf("ExecutablePath = %q, want %q", h.ExecutablePath, codexPath)
+ }
+ if h.Version != "codex 1.2.3" {
+ t.Fatalf("Version = %q, want fake executable version", h.Version)
+ }
+}
+
func TestCodexStatusVariants(t *testing.T) {
dir := t.TempDir()
tests := []struct {
diff --git a/cli/beacon/internal/endpoint/hooks/cursor.go b/cli/beacon/internal/endpoint/hooks/cursor.go
index 8c6b5347..537b4e7c 100644
--- a/cli/beacon/internal/endpoint/hooks/cursor.go
+++ b/cli/beacon/internal/endpoint/hooks/cursor.go
@@ -61,7 +61,7 @@ func InstallCursor(opts CursorOptions) (CursorStatus, error) {
return CursorStatus{}, err
}
hooksPath := filepath.Join(targetDir, "hooks.json")
- if err := installCursorHooksJSON(hooksPath, binaryPath, opts.LogPath); err != nil {
+ if err := installCursorHooksJSON(hooksPath, binaryPath, opts.LogPath, endpointconfig.ConfigPath(opts.UserMode)); err != nil {
return CursorStatus{}, err
}
return CursorStatus{Installed: true, BinaryPath: binaryPath, HooksJSONPath: hooksPath, Message: "Cursor endpoint hooks installed"}, nil
@@ -116,12 +116,12 @@ func IsCursorInstalled(opts CursorOptions) bool {
return strings.Contains(string(data), "BEACON_ENDPOINT_MODE=1") && strings.Contains(string(data), "beacon-hooks")
}
-func installCursorHooksJSON(path, binaryPath, logPath string) error {
+func installCursorHooksJSON(path, binaryPath, logPath, configPath string) error {
hooksJSON, err := readHooksJSON(path)
if err != nil {
return err
}
- commandPrefix := fmt.Sprintf("BEACON_ENDPOINT_MODE=1 BEACON_ENDPOINT_LOG=%s %s --platform cursor", shellQuote(logPath), shellQuote(binaryPath))
+ commandPrefix := fmt.Sprintf("BEACON_ENDPOINT_MODE=1 BEACON_ENDPOINT_LOG=%s BEACON_ENDPOINT_CONFIG=%s %s --platform cursor", shellQuote(logPath), shellQuote(configPath), shellQuote(binaryPath))
endpointHooks := map[string]HookRef{
"sessionStart": {Command: commandPrefix + " session-start"},
"beforeSubmitPrompt": {Command: commandPrefix + " prompt-submit", Timeout: 30},
diff --git a/cli/beacon/internal/endpoint/hooks/cursor_test.go b/cli/beacon/internal/endpoint/hooks/cursor_test.go
index 2946589f..bf8b843e 100644
--- a/cli/beacon/internal/endpoint/hooks/cursor_test.go
+++ b/cli/beacon/internal/endpoint/hooks/cursor_test.go
@@ -13,7 +13,7 @@ func TestInstallCursorHooksJSONPreservesNonBeaconHooks(t *testing.T) {
if err := os.WriteFile(path, []byte(existing), 0644); err != nil {
t.Fatal(err)
}
- if err := installCursorHooksJSON(path, "/tmp/beacon-hooks", "/tmp/runtime.jsonl"); err != nil {
+ if err := installCursorHooksJSON(path, "/tmp/beacon-hooks", "/tmp/runtime.jsonl", "/tmp/config.json"); err != nil {
t.Fatal(err)
}
data, err := os.ReadFile(path)
@@ -30,6 +30,9 @@ func TestInstallCursorHooksJSONPreservesNonBeaconHooks(t *testing.T) {
if !strings.Contains(text, "BEACON_ENDPOINT_LOG='/tmp/runtime.jsonl'") {
t.Fatalf("endpoint log env was not added: %s", text)
}
+ if !strings.Contains(text, "BEACON_ENDPOINT_CONFIG='/tmp/config.json'") {
+ t.Fatalf("endpoint config env was not added: %s", text)
+ }
}
func TestRemoveEndpointHooksPreservesOtherHooks(t *testing.T) {
@@ -115,7 +118,7 @@ func TestInstallCursorHooksJSONReplacesExistingBeaconHook(t *testing.T) {
t.Fatal(err)
}
- if err := installCursorHooksJSON(path, "/tmp/new beacon-hooks", "/tmp/runtime's.jsonl"); err != nil {
+ if err := installCursorHooksJSON(path, "/tmp/new beacon-hooks", "/tmp/runtime's.jsonl", "/tmp/config path.json"); err != nil {
t.Fatalf("installCursorHooksJSON returned error: %v", err)
}
data, err := os.ReadFile(path)
@@ -131,6 +134,9 @@ func TestInstallCursorHooksJSONReplacesExistingBeaconHook(t *testing.T) {
if !strings.Contains(string(data), "'/tmp/new beacon-hooks'") || !strings.Contains(string(data), "BEACON_ENDPOINT_LOG=") || !strings.Contains(string(data), "runtime") {
t.Fatalf("command values were not shell-quoted: %s", string(data))
}
+ if !strings.Contains(string(data), "BEACON_ENDPOINT_CONFIG='/tmp/config path.json'") {
+ t.Fatalf("endpoint config path was not shell-quoted: %s", string(data))
+ }
}
func TestInstallCursorWithUnknownLevelFailsBeforeWritingTarget(t *testing.T) {
diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
index 45c07a92..c4ee772e 100644
--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
@@ -82,12 +82,9 @@ func Install(opts InstallOptions) (InstallResult, error) {
return InstallResult{}, err
}
manager := service.Manager{UserMode: cfg.UserMode}
- collectorBinary := endpointcollector.DiscoverBinary(cfg.Collector.BinaryPath)
- if collectorBinary == "" {
- collectorBinary = cfg.Collector.BinaryPath
- }
- if collectorBinary == "" {
- collectorBinary = filepath.Join(endpointconfig.BaseDir(cfg.UserMode), "bin", "beacon-otelcol")
+ collectorBinary, err := endpointcollector.ResolveBinary(cfg.Collector.BinaryPath)
+ if err != nil {
+ return InstallResult{}, err
}
manifest := Manifest{
diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go
index d2bf50c3..500830a1 100644
--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go
+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle_test.go
@@ -273,7 +273,7 @@ func TestInstallUserModeWithoutStartingService(t *testing.T) {
}
home := t.TempDir()
t.Setenv("HOME", home)
- collectorPath := filepath.Join(home, "bin", "otelcol")
+ collectorPath := filepath.Join(home, "bin", "beacon-otelcol")
if err := os.MkdirAll(filepath.Dir(collectorPath), 0755); err != nil {
t.Fatalf("mkdir fake collector dir: %v", err)
}
@@ -311,6 +311,34 @@ func TestInstallUserModeWithoutStartingService(t *testing.T) {
}
}
+func TestInstallFailsBeforeWritingArtifactsWhenCollectorMissing(t *testing.T) {
+ if runtime.GOOS != "darwin" {
+ t.Skip("install preflight is macOS-only")
+ }
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ logPath := filepath.Join(home, ".beacon", "endpoint", "logs", "runtime.jsonl")
+ missingCollector := filepath.Join(home, "bin", "beacon-otelcol")
+
+ _, err := Install(InstallOptions{
+ UserMode: true,
+ LogPath: logPath,
+ Harnesses: []string{""},
+ GRPCPort: freePort(t),
+ HTTPPort: freePort(t),
+ CollectorPath: missingCollector,
+ StartService: false,
+ })
+ if err == nil || !strings.Contains(err.Error(), "collector binary") || !strings.Contains(err.Error(), "not usable") {
+ t.Fatalf("Install error = %v, want missing collector error", err)
+ }
+ for _, path := range []string{endpointconfig.ConfigPath(true), logPath} {
+ if _, statErr := os.Stat(path); !os.IsNotExist(statErr) {
+ t.Fatalf("%s exists or unexpected error after failed install: %v", path, statErr)
+ }
+ }
+}
+
func freePort(t *testing.T) int {
t.Helper()
ln, err := net.Listen("tcp", "127.0.0.1:0")
diff --git a/cli/beacon/internal/endpoint/service/service.go b/cli/beacon/internal/endpoint/service/service.go
index bc3339e2..5c476686 100644
--- a/cli/beacon/internal/endpoint/service/service.go
+++ b/cli/beacon/internal/endpoint/service/service.go
@@ -25,6 +25,12 @@ type Status struct {
Message string `json:"message,omitempty"`
}
+var runLaunchctlCommand = func(args ...string) (string, error) {
+ cmd := exec.Command("launchctl", args...)
+ out, err := cmd.CombinedOutput()
+ return string(out), err
+}
+
func (m Manager) Label() string {
if m.UserMode {
return UserLabel
@@ -66,20 +72,16 @@ func (m Manager) Load() error {
if err != nil {
return err
}
- if m.UserMode {
- return runLaunchctl("bootstrap", "gui/"+fmt.Sprint(os.Getuid()), path)
- }
- return runLaunchctl("bootstrap", "system", path)
+ domain := serviceDomain(m.UserMode)
+ return runLaunchctlWithContext(domain, m.Label(), path, "bootstrap", domain, path)
}
func (m Manager) Unload() error {
if runtime.GOOS != "darwin" {
return nil
}
- if m.UserMode {
- return runLaunchctl("bootout", "gui/"+fmt.Sprint(os.Getuid())+"/"+m.Label())
- }
- return runLaunchctl("bootout", "system/"+m.Label())
+ target := serviceDomain(m.UserMode) + "/" + m.Label()
+ return runLaunchctlWithContext(serviceDomain(m.UserMode), m.Label(), "", "bootout", target)
}
func (m Manager) Status() Status {
@@ -100,16 +102,55 @@ func (m Manager) Status() Status {
}
func runLaunchctl(args ...string) error {
- cmd := exec.Command("launchctl", args...)
- out, err := cmd.CombinedOutput()
+ return runLaunchctlWithContext("", "", "", args...)
+}
+
+func runLaunchctlWithContext(domain, label, plistPath string, args ...string) error {
+ out, err := runLaunchctlCommand(args...)
if err == nil {
return nil
}
- text := strings.TrimSpace(string(out))
+ text := strings.TrimSpace(out)
if strings.Contains(text, "already bootstrapped") || strings.Contains(text, "No such process") {
return nil
}
- return fmt.Errorf("launchctl %s failed: %s: %w", strings.Join(args, " "), text, err)
+ context := launchctlContext(domain, label, plistPath)
+ guidance := launchctlGuidance(text, domain, label)
+ if guidance != "" {
+ return fmt.Errorf("launchctl %s failed%s: %s: %w\n%s", strings.Join(args, " "), context, text, err, guidance)
+ }
+ return fmt.Errorf("launchctl %s failed%s: %s: %w", strings.Join(args, " "), context, text, err)
+}
+
+func launchctlContext(domain, label, plistPath string) string {
+ var fields []string
+ if label != "" {
+ fields = append(fields, "label "+label)
+ }
+ if domain != "" {
+ fields = append(fields, "domain "+domain)
+ }
+ if plistPath != "" {
+ fields = append(fields, "plist "+plistPath)
+ }
+ if len(fields) == 0 {
+ return ""
+ }
+ return " (" + strings.Join(fields, ", ") + ")"
+}
+
+func launchctlGuidance(output, domain, label string) string {
+ if !strings.Contains(output, "Bootstrap failed: 5") && !strings.Contains(output, "Input/output error") {
+ return ""
+ }
+ target := label
+ if domain != "" && label != "" {
+ target = domain + "/" + label
+ }
+ if target == "" {
+ target = "the Beacon launchd job"
+ }
+ return fmt.Sprintf("Bootstrap failed: 5 usually means launchd could not read or execute the job. Verify the collector binary referenced by the plist exists and is executable, clear stale state with `launchctl bootout %s`, then inspect launchd logs with `log show --predicate 'process == \"launchd\"' --last 5m`.", target)
}
func serviceDomain(userMode bool) string {
diff --git a/cli/beacon/internal/endpoint/service/service_test.go b/cli/beacon/internal/endpoint/service/service_test.go
index 175ad467..6c5f2207 100644
--- a/cli/beacon/internal/endpoint/service/service_test.go
+++ b/cli/beacon/internal/endpoint/service/service_test.go
@@ -1,6 +1,7 @@
package service
import (
+ "errors"
"os"
"path/filepath"
"runtime"
@@ -98,3 +99,31 @@ func TestStatusNonDarwinDocumentsUnsupportedMessage(t *testing.T) {
t.Fatalf("unexpected status message: %q", status.Message)
}
}
+
+func TestRunLaunchctlWithContextExplainsBootstrapIOError(t *testing.T) {
+ oldRun := runLaunchctlCommand
+ runLaunchctlCommand = func(args ...string) (string, error) {
+ return "Bootstrap failed: 5: Input/output error", errors.New("exit status 5")
+ }
+ t.Cleanup(func() {
+ runLaunchctlCommand = oldRun
+ })
+
+ err := runLaunchctlWithContext("gui/501", UserLabel, "/Users/test/Library/LaunchAgents/"+UserLabel+".plist", "bootstrap", "gui/501", "/Users/test/Library/LaunchAgents/"+UserLabel+".plist")
+ if err == nil {
+ t.Fatal("runLaunchctlWithContext returned nil, want error")
+ }
+ text := err.Error()
+ for _, want := range []string{
+ "label " + UserLabel,
+ "domain gui/501",
+ "plist /Users/test/Library/LaunchAgents/" + UserLabel + ".plist",
+ "Verify the collector binary",
+ "launchctl bootout gui/501/" + UserLabel,
+ "log show --predicate",
+ } {
+ if !strings.Contains(text, want) {
+ t.Fatalf("error missing %q:\n%s", want, text)
+ }
+ }
+}
diff --git a/packaging/macos/README.md b/packaging/macos/README.md
index d021fe02..44d2d227 100644
--- a/packaging/macos/README.md
+++ b/packaging/macos/README.md
@@ -52,11 +52,16 @@ service.
## Manual Install
```bash
-sudo beacon endpoint install
+sudo beacon endpoint install --system --collector /opt/beacon/bin/beacon-otelcol
beacon endpoint status
beacon endpoint wazuh print-config
```
+Endpoint installs require Beacon's custom `beacon-otelcol` collector because the
+generated Collector config uses the `beaconjson` exporter. The macOS package
+installs it at `/opt/beacon/bin/beacon-otelcol`; CLI-only installs must place
+`beacon-otelcol` on `PATH` or pass `--collector`.
+
## Smoke Test
Run the non-root endpoint smoke test on a macOS host or VM: