Skip to content

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

Add binary-path GitHub Actions reference workflow.

Ayush7614a8ca80190a48
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index ad9501bd..9a84d839 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -293,7 +293,11 @@ A composite action wraps binary resolution, `ci exec`, session
The action downloads a pinned Beacon release and verifies it against the
release `checksums.txt` before running. When the action is invoked from a
version tag, that tag is used as the default Beacon CLI release; set `version`
-explicitly or use `binary-path` when testing from a branch or local checkout.
+explicitly or use `binary-path` when testing from a branch or local checkout,
+or on air-gapped and self-hosted runners that already provide `beacon` and
+`beacon-otelcol`. See
+[`examples/github-actions/binary-path-telemetry.yml`](../../examples/github-actions/binary-path-telemetry.yml)
+for a complete reference workflow.
It uploads the runtime JSONL log as an artifact by default.
To wrap a third-party agent action, split the action into `start` and `finish`
@@ -377,7 +381,8 @@ See [`examples/github-actions/claude-code-telemetry.yml`](../../examples/github-
[`examples/github-actions/codex-action-session.yml`](../../examples/github-actions/codex-action-session.yml),
[`examples/github-actions/s3-upload-telemetry.yml`](../../examples/github-actions/s3-upload-telemetry.yml),
[`examples/github-actions/gcs-upload-telemetry.yml`](../../examples/github-actions/gcs-upload-telemetry.yml),
-and [`examples/github-actions/splunk-forward-telemetry.yml`](../../examples/github-actions/splunk-forward-telemetry.yml)
+[`examples/github-actions/splunk-forward-telemetry.yml`](../../examples/github-actions/splunk-forward-telemetry.yml),
+and [`examples/github-actions/binary-path-telemetry.yml`](../../examples/github-actions/binary-path-telemetry.yml)
for complete reference workflows.
## Wazuh
diff --git a/docs/log-forwarding/ci-telemetry-exports.mdx b/docs/log-forwarding/ci-telemetry-exports.mdx
index 0a5e1e08..932c9fcf 100644
--- a/docs/log-forwarding/ci-telemetry-exports.mdx
+++ b/docs/log-forwarding/ci-telemetry-exports.mdx
@@ -196,6 +196,23 @@ By default, `beacon ci exec` fails the step when telemetry validation fails. Set
Object storage upload runs after telemetry validation. Upload failures fail the CI step so broken export paths are visible. If the child command exits non-zero, that child exit code still takes precedence.
+### Air-gapped and self-hosted binary-path
+
+When runners should not download a Beacon release during the action step, provision `beacon` and `beacon-otelcol` side by side (from an internal mirror or pre-baked image), then pass `binary-path` to the action:
+
+```yaml
+- name: Run Claude with Beacon telemetry
+ uses: asymptote-labs/[email protected]
+ with:
+ binary-path: /opt/beacon/bin/beacon
+ command: claude --print "Review this pull request"
+ upload-artifact: "true"
+```
+
+See the sample workflow:
+
+- [binary-path telemetry workflow](https://github.com/Asymptote-Labs/agent-beacon/blob/main/examples/github-actions/binary-path-telemetry.yml)
+
## Related
<Columns cols={2}>
diff --git a/examples/github-actions/binary-path-telemetry.yml b/examples/github-actions/binary-path-telemetry.yml
new file mode 100644
index 00000000..07dddeed
--- /dev/null
+++ b/examples/github-actions/binary-path-telemetry.yml
@@ -0,0 +1,69 @@
+# Reference workflow for running Agent Beacon CI telemetry with a
+# pre-provisioned beacon binary via binary-path. Use this when runners are
+# air-gapped or self-hosted and should not download a Beacon release from
+# GitHub during the action step.
+#
+# This file lives under examples/ (not .github/workflows/) so it is a
+# reference only and does not run in this repository.
+# Replace <tag> with the Beacon release tag you want to run. The beacon
+# and beacon-otelcol binaries must live side by side in BEACON_BIN_DIR.
+
+name: Test Agent Beacon binary-path
+
+on:
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+env:
+ # Pin the Beacon release whose binaries you vendor or download once.
+ BEACON_VERSION: v0.0.49
+
+jobs:
+ beacon-binary-path:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Provision Beacon binaries
+ env:
+ BEACON_BIN_DIR: ${{ runner.temp }}/beacon-bin
+ run: |
+ set -euo pipefail
+ mkdir -p "${BEACON_BIN_DIR}"
+ # Air-gapped runners: replace this download with a copy from an
+ # internal mirror or pre-baked image path that already contains
+ # beacon and beacon-otelcol next to each other.
+ os=linux
+ arch="$(uname -m)"
+ case "${arch}" in
+ x86_64|amd64) arch=amd64 ;;
+ aarch64|arm64) arch=arm64 ;;
+ *) echo "unsupported arch ${arch}"; exit 1 ;;
+ esac
+ ver_no_v="${BEACON_VERSION#v}"
+ archive="beacon_${ver_no_v}_${os}_${arch}.tar.gz"
+ base="https://github.com/asymptote-labs/agent-beacon/releases/download/${BEACON_VERSION}"
+ curl -fsSL "${base}/${archive}" -o "${BEACON_BIN_DIR}/${archive}"
+ curl -fsSL "${base}/checksums.txt" -o "${BEACON_BIN_DIR}/checksums.txt"
+ expected="$(grep " ${archive}\$" "${BEACON_BIN_DIR}/checksums.txt" | awk '{print $1}')"
+ actual="$(sha256sum "${BEACON_BIN_DIR}/${archive}" | awk '{print $1}')"
+ test "${expected}" = "${actual}"
+ tar -xzf "${BEACON_BIN_DIR}/${archive}" -C "${BEACON_BIN_DIR}"
+ chmod +x "${BEACON_BIN_DIR}/beacon" "${BEACON_BIN_DIR}/beacon-otelcol"
+ test -x "${BEACON_BIN_DIR}/beacon"
+ test -x "${BEACON_BIN_DIR}/beacon-otelcol"
+ echo "BEACON_BIN_DIR=${BEACON_BIN_DIR}" >> "${GITHUB_ENV}"
+
+ - name: Install Claude Code
+ run: npm install -g @anthropic-ai/claude-code
+
+ - name: Run Agent Beacon with binary-path
+ uses: asymptote-labs/agent-beacon@<tag>
+ env:
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+ with:
+ binary-path: ${{ env.BEACON_BIN_DIR }}/beacon
+ command: claude --print "Say hello from Agent Beacon CI telemetry"
+ upload-artifact: "true"