The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
CLAUDE.md
Guidance for Claude Code and other coding agents working in this repository.
Project Scope
Beacon Endpoint Agent is a local-only endpoint telemetry agent for AI runtimes. The shipping code paths are:
cli/beacon: publicbeaconCLI and endpoint runtime.cli/beacon-hooks: hook adapter invoked by Cursor and other supported runtimes.collector-builder: OpenTelemetry Collector distribution and Beacon JSONL exporter.packages/asymptote-sdk-js: TypeScript SDK for cloud agent telemetry that exports Beacon-compatible OpenTelemetry spans.browser-extension: optional MV3 collector (Chrome, plus a beta Firefox build target) that relays Claude.ai and ChatGPT chat telemetry into the local pipeline as OTLP.pkg/asymptoteobserve: shared Go library — event schema, harness-name normalization, provenance markers, token usage, runtime log modes and the local ingest channel (localingest), and the threat-rules engine. Imported by the CLI, the hook adapter, and the collector exporter, so a change here reaches all three.plugins: TypeScript sources for the managed runtime plugins/extensions (opencode-beacon,cline-beacon,pi-beacon,omp-beacon,openclaw-beacon,prime-beacon,omo-beacon), each mirrored into an embedded copy undercli/beacon/internal/endpoint/hooks/assets/.agent-skills: publishable Agent Skills plugin for the traces-to-memory workflow (beacon-memory-recall,beacon-memory-distill,beacon-memory-promote), for authoring dashboard lenses (beacon-lens-create), for sharing the current session to beacon.sh (beacon-trace-share, which runsbeacon share --current --harness <runtime> --json, keeps the default direct visibility and asks before public), and for continuing local sessions in another runtime (beacon-session-handoff, which uses detached CLI launch) with manifests for Claude Code, Agent Plugins (Codex, Copilot, VS Code, Kiro, Devin), Cursor, Kimi Code, and Gemini CLI. At the repo root,.claude-plugin/marketplace.jsonis read by most harnesses,.cursor-plugin/marketplace.jsonby Cursor, andpackage.json(pi.skillsonly) makes the repo a Pi/Prime Agent package; keep that rootpackage.jsonfree of dependencies and scripts.cli/beacon/cmd/agent_skills_test.gochecks everybeaconcommand and flag the skills name against the real command tree, so rename a command and update the skills together. The binary carries a copy ofagent-skills/skillsincli/beacon/internal/agentskills/skillsfor onboarding andbeacon skills install; a test keeps it identical, so copy it across whenever a skill changes.rulesandspec/threat-rules: the open rule corpus and the Threat Rules format it conforms to. Every rule'staxonomy.beacon_categoryis its directory name, and the six embedded baseline rules inpkg/asymptoteobserve/rulestore/baselineare byte-identical copies of their corpus rules; conformance tests enforce both.spec/lenses: the Lenses format — single-file HTML views of one trace that the local dashboard runs in a sandboxed, network-less frame and feeds once throughwindow.beacon.getTrace(). The contract types (LensManifestV1,LensDataV1) live inpkg/asymptoteobserve/lens.go, andlens_test.gopins the spec's examples and manifest schema to them. The dashboard builds the data inBuildLensData(/api/lens-data), lists lenses at/api/lenses, and serves each lens at/lenses/frame/<id>under the spec's CSP withlenses/prelude.js(which defineswindow.beacon) injected ahead of it; that route is the only one that may be framed. Built-in lenses arecli/beacon/internal/endpoint/dashboard/lenses/*.lens.html, andactivityis byte-identical to the spec example (a test enforces it). The session page (static/session.html,initLensTabsinapp.js) shows lenses as tabs fed by/api/lens-data?session=, which projects exactly the events that page lists; it is the host half of the protocol and closes a lens that errors, stalls, or navigates its own frame. Trust model (SPEC "Trust model"): the opaque origin, sandbox and CSP keep a lens from touching Beacon or the dashboard and block ordinary network APIs, but cannot fully prevent a lens from sending trace data out through browser features no CSP governs (WebRTC, resource hints, speculative loading), so an installed lens is code the person trusts with the trace data it is shown; never describe the sandbox as making exfiltration impossible.prelude.jsremoves theRTC*globals and guards the document (refuses creating, inserting or parsing in nested frames,<link>elements and<script type=speculationrules>, parsing markup in the real call's document and context and inserting exactly the checked nodes so<noscript>/foreign-content parser differentials cannot slip through, refusesdocument.writeandexecCommand("insertHTML"), and a mutation observer removes those from the file's own markup); that is best-effort hardening, not a boundary, and the hostileprobefixture intestdata/lens-e2epins each covered path. Installed lenses live in the lens store (cli/beacon/internal/endpoint/lensstore,<BaseDir>/lenses/<id>.lens.html, 0600 under 0700), written only bybeacon lenses add|remove(cli/beacon/cmd/lenses.go;addprints the trust warning and confirms on a TTY, and refuses without one or in CI unless--yes); the dashboard rescans it per request and never writes it, and a store lens can never shadow a built-in.asymptoteobserve.CheckLensFileis the one file check every installer, server and linter uses. User docs aredocs/concepts/lenses.mdxanddocs/cli/lenses.mdx; keep them in sync with the commands and built-in lenses. The authoring loop isbeacon lenses spec(the spec carried in the binary asdashboard/lenses/SPEC.md, kept byte-identical tospec/lenses/SPEC.mdby a test),beacon lenses data(the exactLensDataV1for a session),beacon lenses lint(lensstore.Lint; built-ins must lint clean) andbeacon lenses preview(the dashboard withOptions.LensFiles, re-read per reload).beacon-sandbox: harness that runs a real Claude Code session in a disposable sandbox and checks what Beacon captured. Seebeacon-sandbox/AGENTS.md.packaging: macOS, Linux, and Windows packaging and deployment assets.terraform: customer-run Terraform modules for the cloud side of object storage forwarding. The base modulesaws-s3andgcsalways create a new, dedicated bucket (never an existing one) and the writer every Mac's forwarder uses: the put-onlybeacon-endpoint-writerIAM user, or abeacon-endpoint-writerservice account withobjectCreatorlimited to the prefix by an IAM condition. The enterprise self-hosted path, where Asymptote reads that bucket through ClickHouse, is two separate modules that take the base module'sbucketoutput:aws-s3-asymptote-reader(anasymptote-s3-readerIAM user, because ClickPipes on the GCP-hosted ClickHouse rejects IAM roles, plus an SQS queue and dead-letter queue per stream and the bucket notification, which it owns) andgcs-asymptote-reader(objectViewerforbeacon-clickpipes-reader@asymptote-labs, a Pub/Sub topic, the notification and a subscription per stream with the managed path's settings). The queues exist because a ClickPipe without one reads in key order and skips objects that land behind its cursor, which Macs uploading on their own timers cause; their URLs and subscription paths are outputs for the provisioning script's--queue-url. Keep everything Asymptote-specific out of the base modules. No module creates keys unless asked (create_writer_access_key,create_writer_key,create_access_key), so no secret lands in state by default. Resource names andforwarder_settingsmatch the packagedinstall-forwarder.shhelpers and the manual guides. docs.beacon.sh (docs/log-forwarding/{aws-s3,gcs}-terraform.mdx) documents the base modules only. The reader modules and the self-hosted setup are documented only on docs.asymptotelabs.ai (beacon-mdrdocs/deployment/self-hosted-{s3,gcs}.mdx), so keep them out ofdocs/;/manage/configure-s3-data-connectorredirects there. Both sites pin the modules to a release tag; keep them in sync with the variables.docs: the published documentation site (docs.asymptotelabs.ai).
Do not recreate or depend on removed asymptote mirror trees. Keep new work focused on the Beacon paths above.
Product Posture
- Beacon is visibility-first endpoint telemetry for local AI agent runtimes, not a hosted policy service or general endpoint protection product.
- Preserve the local-only default. The public Beacon build must not require a hosted account, remote policy fetch, hosted dashboard, or external network dependency during normal hook execution, and hooks themselves never touch the network.
beacon loginis the account-identity channel for interactive users and is required by the interactivebeacon endpoint installwizard. It uses browser PKCE against beacon.sh and stores the scoped CLI token only in~/.beacon/auth/session.json(0600 under a 0700 directory). Signing in alone never starts forwarding. User-modebeacon endpoint connectmay send that token once toPOST /api/cli/enroll/accountto authorize minting a separate device ingest key, andbeacon mcp token createmay send it toPOST /api/cli/mcp/tokens(scopemcp:token:create, listed on the sign-in page) to mint a personal MCP token that is printed once to stdout and never written to a file, andbeacon sharemay send it (scopetraces:write, also on the sign-in page) toPUT /v1/traces/{external_id},POST /v1/traces/{external_id}/events/batchandGET /v1/traces/{external_id}on the Beacon API host (https://api.beacon.shfor a beacon.sh sign-in, other hosts unchanged,BEACON_API_URLoverrides) to upload a shared trace the person chose to publish, as abeacon.trace.v1summary and its events (cli/beacon/internal/account/share.go; abcn_api_API key from--keyorBEACON_API_KEYmay stand in for it, precedence--key, then a current sign-in carrying the scope, then the environment). These are explicit, user-initiated requests with redirects refused. Hooks, plugins and background jobs never make them, with one exception: the git pre-push hook, only when the person opted in withbeacon git setup --share-sessions(public needs confirmation), may make the three share requests during a push the person started, within the hook's budget and never failing the push. Never copy the account token into endpoint config, Vector, hook environments, logs, or command output. System/root/package/MDM/CI/piped-stdin/dry-run installs stay noninteractive and account-free.- System log access (
beacon endpoint install|repair --system --log-access shared|restricted; docs indocs/cli/endpoint-install.mdx#restricted-log-access). Shared, the CLI default, is the system log as it always was: hooks append to/var/log/beacon-agent/runtime.jsonldirectly, so it is0666. Restricted is opt-in for the CLI and the default for a first package install on every platform (see below; on Linuxpackaging/linux/install-endpoint.shpasses--log-access restrictedonly when neither the systemconfig.jsonnor the runtime log exists,/proc/1/commis systemd andBEACON_SERVICEis unset,autoorsystemd; otherwise it passes nothing and the endpoint keeps its mode;packaging/linux/beacon-settings.sh, sourced by that script and by the postinstall (which takes onlyBEACON_ENDPOINT_HARNESSES, throughbeacon_settings_harnessesin a subshell, because its user-config step re-runs the CLI as each logged-in user with its environment and must not hand them a Splunk HEC token from the file), reads theBEACON_*install settings, never sourcing the file, from a root-owned, not group/other-writable/etc/default/beaconor/etc/sysconfig/beaconin shell syntax with trailing comments, skipping a malformed value with a warning naming only the key, the last assignment of a key winning within the file, the environment andinstall-endpoint.sh's positional arguments winning over it; the postinstall prints theusermod -aG beacon-loghint for a restricted log;packaging/linux/test-endpoint-scripts.shchecks all of it). Restricted makes the root collector the only writer: itsbeacon_ingestextension (collector-builder/exporter/beaconjsonexporter/beaconingestextension, appending through the exporter's owninternal/runtimelog) serves/var/run/beacon-agent/ingest.sock, and the hook adapter and the CLI writer, as any account but root writing the system log, hand finished lines to it throughpkg/asymptoteobserve/localingest(Deliverer). The protocol is one batch per connection (BEACON-INGEST/1, a header naming the log, one event per line, one JSON reply saying how far it got); the server refuses a batch for any log but its own, identifies the sender only by kernel peer credentials (SO_PEERCRED,LOCAL_PEERCRED), overwrites the event'suserwith that uid and its resolved name and always derivesevent.iditself (StampLinere-encodes, so a sender cannot split or forge lines or reuse another event's id), and bounds connections overall and per uid, batch size, each account's bytes per second, and its own time per connection (shorter than the client's, so it reports how far it got instead of being resent). The client sends only to a socket that root owns in a directory nobody else can write, under ancestors owned by root or by the sending account (a sandbox without a user namespace, such as bubblewrap, assembles its root on a tmpfs that account owns, so a bind-mounted/var/run/beacon-agentworks there; group-writable ancestors only for gid 0/1, which macOS's/private/var/runneeds), and only once the connected socket's own peer credentials name root as the server (checkServer), so no swap of the path between the check and the dial reaches another listener. Sandboxes with their own user namespace are out of scope.Deliverer.Writesends through the socket when it answers and otherwise appends directly as before; only a direct append that cannot reach the log (refused for permission, its directory missing, or a read-only mount: a restricted log whose collector is down, or a sandbox that leaves the log out) spools the line, to the account's private spool for that log (~/.beacon/endpoint/spool/<log digest>, 0600 under 0700, only in a home that exists), and the next line that gets through either way drains it. Root writers and per-user logs always write directly. No ordinary account creates the system log's directory, and no writer creates a missing home to hold a log (asymptoteobserve.RuntimeLogDirCreatable) or the hook's state directories, so a sandbox whose root filesystem is its own gets aNOT recordedexplanation on stderr instead of events written into its tmpfs. The mode isconfig.jsonlog_access, carried through repair and package upgrades (BEACON_LOG_ACCESSin the install scripts). A first install from any package (.deb/.rpmon systemd hosts, the macOS.pkg, the MSI unlessBEACON_SERVICEnames the supervised collector; no system config and no kept log) defaults to restricted in its install script, and adds tobeacon-log(--log-readers,loggroup.AddMember: gpasswd/addgroup, dseditgroup, net.exe; add-only, failures reported not fatal;validAccountalso admits spaces, an apostrophe and non-ASCII letters on Windows, because OOBE names local accounts from what the person typed) exactlyBEACON_LOG_READERSwhen set, even empty, else only a person who installed interactively (LinuxSUDO_USERwith a controlling terminal (/dev/tty, not stdin, which rpm scriptlets get as a pipe) and notDEBIAN_FRONTEND=noninteractive, because Ansiblebecomeand Packer sudo setSUDO_USERtoo; macOS withoutCOMMAND_LINE_INSTALLand with anInstallerprocess of the console user whose lsoftxtexecutable is Apple's/System/Library/CoreServices/Installer.app, never a bare process name; Windows MSIUILevel>= 4 via the custom action's-UiLevel), never an unattended fleet install. In both shell settings parsers an environment variable set to an empty string counts as unset (exceptBEACON_LOG_READERS, where empty means nobody), and the macOS Fleet wrapper (packaging/macos/fleet/scripts/install.sh) passes only arguments it was given, so neither hides the settings file or managed preferences. Fleet tooling sets theBEACON_*install settings where it writes settings:/etc/default/beacon//etc/sysconfig/beacon(packaging/linux/beacon-settings.sh), managed or local preferences forcom.beacon.endpoint(packaging/macos/beacon-settings.sh),HKLM\SOFTWARE\Policies\Beacon\Endpoint(install-endpoint.ps1); each read only when root/admin-controlled, environment wins; docs indocs/security/restricted-log-access.mdx#package-installs. Install creates thebeacon-loggroup (internal/endpoint/loggroup, getent/groupadd, dscl/dseditgroup) andwriter.RestrictSystemLogmakes the directoryroot:beacon-log 02750, the log and archives0640and the lock root-only0600, after writing the root-owned.beacon-log-accessmarker beside the log; a shared log is not narrowed in place but copied to fresh root-created files and renamed over, under its lock (bounded wait), because a descriptor opened while it was 0666 survives any chmod. A failed install restores the previous mode in its rollback (logAccessRestorer), or, when there was no log before, removes the log, lock and marker it created, because every package script reads a log without a system config as one kept by--keep-logs, which would turn the retry of a failed first install into an upgrade; and a shared install removes a dead socket. The marker is what tells every root writer (asymptoteobserve.RuntimeLogModes) to keep the restricted modes. The OTLP receivers on loopback are not covered by the socket: any local process can still send OTLP. On Linux, macOS and Windows those events are attributed to the account that owns the sending socket (peer attribution, below), which names the sender but does not stop an account sending what it likes under its own name, so never claim more than that. Doctor'sruntime_log_accesscovers the marker, the socket and pending spool. Unix sockets are local IPC, not a network channel, so the hooks-never-touch-the-network rule holds. On Windows the same mode runs over the named pipe\\.\pipe\beacon-agent-ingest(localingesttransport_windows.go, go-winio): the collector creates it as the first instance, and when the name is taken (any account may create one) it reports a recoverable error and retries every few seconds rather than failing, so the rest of the collector stays up; it rejects remote clients and its DACL denies NETWORK and withholdsFILE_CREATE_PIPE_INSTANCEfrom ordinary accounts, so it is not a network channel either; a client connects at identification level and sends only to a pipe owned by SYSTEM or Administrators; the server counts a connection against its account from the client process's token before reading and stamps the SID it reads byImpersonateNamedPipeClientafter the preamble (they must agree), withPeer.UIDa string (decimal uid on Unix, SID on Windows) and the name fromLookupAccountSid, bounded. Privileged writers there are SYSTEM and tokens with Administrators enabled (CheckTokenMembership; elevation for another group is not enough). The directory getssysacl.RestrictedLogDirDACL(protected: SYSTEM and Administrators full,beacon-loglocal group read, nothing else; the lock SYSTEM and Administrators only) and everything below it is reset, because every account may bypass traverse checking;writer.RestrictSystemLogreplaces every file directly in the directory (the log family under the lock; files outside it with another hard link are skipped) with a copy created with its final owner and DACL (sysacl.CreateRestrictedFile) and a POSIX-semantics rename, fails naming any file held open without sharing delete and then puts a log that was shared back to shared, and writes the marker last (on Windows it decides nothing for root writers, so a failed or killed run is not mistaken for a finished one). The marker counts there when SYSTEM or Administrators own it and no other account can write it.loggroupcreates the local group withnet.exeand looks it up qualified with the computer name. Doctor reads the restricted ACL (writer.CheckRestrictedSystemLogACL).packaging/windows/smoke-restricted-log.ps1runs inwindows-package-smokeagainst the installed MSI with a real ordinary account. Hook and writer tests pointlogging.EndpointIngest/writer.Ingestat sockets of their own.- Sandbox roots (Linux): no unprivileged writer puts the log directory (
RuntimeLogDirCreatable) or the account spool (DefaultSpoolDirreturns "") on the throwaway root of a sandbox it assembled (asymptoteobserve.OnSandboxRoot:/a tmpfs owned by this non-root account, and the path's nearest existing directory on that filesystem). Both conditions matter: a persistent account-owned/(a rootfs bound at/, an Apptainer sandbox) keeps its writes. The home-exists checks alone are not enough, because a launcher that binds a project under the home makes bwrap create the home as an empty mount point on its tmpfs. Hook state and the active-session record may still go there: they are per-session dedupe, and refusing them re-records prompts on every tool call. What the sandbox bind-mounts is another filesystem and is written as usual: a mounted~/.beacon/endpoint/spoolspools for real, and a workspace is where #1284's workspace spool stages.
- Sandbox roots (Linux): no unprivileged writer puts the log directory (
- Workspace spool (
pkg/asymptoteobserve/workspacespool.go,cli/beacon/internal/workspacespool,beacon endpoint spool drain|status; docs indocs/cli/endpoint-spool.mdx). A hook of any harness that cannot deliver an event by any other route (socket, log, account spool) stages it in<workspace>/.beacon/spool/<harness>/<session>/(alocalingest.Spool), because a sandbox that confines hook writes to the session workspace (DeepSeek Harness #605, container and operator sandboxes #1284) still lets it write there;.beacon/dsh-spool/<session>is an earlier layout drains still empty. A.gitignoreof*in.beacon/spool/(and.git/info/exclude) keeps it out of an agent'sgit add -A, since it holds prompts; it is a precondition of staging (ensureSpoolGitignore, checked before every append): created when missing, never overwritten, and when one is already there (a repository can commit its own) staging goes ahead only if it is a regular file that ignores*and negates nothing. It never stages a Beacon-only action (drains refuse them, sorequestShareOncemust see the failure and take its mark back), on a sandbox's own root filesystem (OnSandboxRoot), or as root in a workspace another account owns (rootInAnotherAccountsWorkspace, which the hook's own drain also honors): a rootful container over the user's checkout would leave root-owned 0700/0600 files the user can neither drain nor delete, and a root drain would rewrite the user'spending.jsonlas root's; root that owns the workspace (a rootless container) stages as anyone. The first event a session stages prints one stderr note with a shell-quotedbeacon endpoint spool drain --log-path … --workspace … --harness … --session …naming the hook's own log and that session alone (not printed for DeepSeek Harness, whose store-backeddsh syncfinds it). The threat model is untrusted workspace content: a cloned repository and the sandboxed agent itself. So every drain admits a line only throughAdmitStagedLine(Beacon envelope, that harness and session, hook or plugin collection, not a Beacon-only action: a plantedsession.share_requestedwould publish a session), the CLI drains also throughEvent.Validate(a refused line is removed, never left to block the spool), an admitted line is written again through the writer's own encoder (hook:encodeEndpointLine; CLI:writer.AppendEvent), and only sessions Beacon has recorded in the runtime log tail are drained (KnownSessions; the default log when no config exists), or those under the operator'sconfig.jsonworkspace_spool_roots(globs, kept through repair) or a--workspacethe person names (literal, never a glob;--harness/--sessionnarrow it). Every component below the workspace must be a real directory and the spool file a regular file no larger thanDefaultSpoolMaxBytes(Appendnever grows one past it, so a bigger one was written by hand), Lstat-checked (realSpool,spoolPathIsReal) and openedO_NOFOLLOW|O_NONBLOCK, because the agent knows its own session id and could plant that directory as a link to the account spool, which a drain outside the sandbox would then empty. The CLI drains each spool in oneSpool.Drainpass (one read, one rewrite of the remainder): batches would re-read and rewrite the whole file each time. Deliberately not defended, because they need an unguessable session id or an agent actively racing renames against a drain for a negligible payoff (the agent can already rewrite its own staged events): spool directories other accounts plant in shared directories, and swaps between the Lstat check and use; do not add ownership checks oros.Rootconfinement for them. A configspool draincannot read (root-only when it holds a destination secret) is never guessed around: without--log-paththe drain refuses and names the flag, and status lists only--workspacespools. Three drains: the user-mode sweep (aWorkspace spoolsstep after the runners, within the budget and retention guard),beacon endpoint spool drain(never as root; in system mode through the socket, without the sweep lock), and the session's own next hook that reaches the log (one batch of 256, its own session only). A confined root sweep (sessionfs.Active) leaves spools alone. Doctor reportsworkspace_spool_pending_drain, anddsh_spool_pending_drainfor DeepSeek Harness. - Beacon Cloud forwarding (
cli/beacon/internal/endpoint/asymptote,beacon endpoint connect,beacon endpoint asymptote) is Vector-shaped: Beacon writes local JSONL, Vector ships runtime lines only from the connection point forward and reads inventory from the beginning to establish the endpoint's current baseline, plus the one bounded exception of the session backfill (below), and thebcn_device_*key stays only in<BaseDir>/asymptote/vector-secrets.jsonvia Vector's secret backend. The onboarding wizard preselects Beacon Cloud, and confirming it connects this endpoint in the same command once the local install has succeeded; an endpoint that is already enrolled is never re-enrolled, because enrollment rotates the device key. Standard mode ships locally sanitized retained content; metadata-only uses local Vector transforms to remove prompts, responses, reasoning, tool arguments/results, tool descriptions/definitions, retrieval queries/documents, evaluation explanations, agent descriptions, stop sequences, approval/policy reasons, command output, raw fields, diffs, inventory content, and MCP definitions before buffering/upload. Every text-shaped event field must be classified inmetadata_fields_test.go(metadataOnlyRemoved, each with its owndel()inpack/metadata-transforms.toml, ormetadataOnlyKept); a new field fails that test until it is, andBEACON_TEST_VECTOR_BINruns the transform on an event with every field set.vector.tomlis not rendered only at connect:asymptote.ReconcileForwarderre-renders it in place for a connected endpoint from the current pack with the enrollment's ingest URL and recorded privacy mode, validates it with the forwarder's own Vector exactly as connect does, atomically replaces it, and, when run from install, repair, the package upgrade or the hidden reconcile the macOS postinstall runs (ReconcileOptions.Restart), restarts a running forwarder even when nothing changed (aftervector validateof the current config with the forwarder's own Vector, and never after a warning, so a refused config or a missing Vector leaves the running forwarder alone), as the Sentinel reconcile does: switching to restricted log access replaces the runtime log with a copy, and Vector, which recognizes a file by its first line, keeps tailing the replaced one until it restarts; an upgrade may also have installed a new Vector. A stopped one is never started and reads the new config when it next starts. Thebeacon_runtimesource readsruntime.jsonl.1too, as the Sentinel pack does, so lines written to a replaced log before a restart are found again at the next rotation instead of lost. It never enrolls, reads or rewrites the secrets file, makes a network request, or touchesvector-data/(checkpoints stay, so pack changes must keep source ids and fingerprinting stable), and a rejected config is a warning that keeps the old one; it is a no-op when not connected, after an incomplete connect, without an installed unit, or whereForwarderManageris unsupported (supervised mode).lifecycle.Installruns it last when services are started (so install, repair and the Linux package upgrade), repair's teardown keeps the forwarder (UninstallOptions.KeepManagedIngest) instead of disconnecting it, and the macOS postinstall, which installs with--no-start, runs the hiddenbeacon endpoint asymptote reconcile --system. Keep the ingest URLhttps://, the wire contract aligned withbeacon-ingest(/v1/ingest/{runtime,inventory}and/v1/ingest/health), and do not add another endpoint network channel. The cloud-sandbox shuttle is the bounded exception: only withBEACON_ORIGIN=cloud, it can upload new runtime lines to GCS, S3, or the same Beacon ingest contract because no Vector/service manager/browser/persistent disk exists there. - Session backfill (
cli/beacon/cmd/endpoint_backfill.go; docs indocs/cli/endpoint-install.mdx#session-backfillanddocs/cli/endpoint-connect.mdx#session-backfill): after every successful install (user or system mode), every session-store collector runs once withCollectOptions.Since(30 days;sessionwindow.Recentkeeps those sessions, newest first, and never touches the cursors of the rest) and a sharedwriter.Budget(24 MiB, at most 12 MiB per runtime throughBudget.Sub; a refused append returnswriter.ErrBudgetSpent, the collector stops with cursors past only what was written, and a manual sync reads the rest). A new session-store collector takes both fields, reads its store only throughinternal/sessionfs(a test parses every collector package to enforce it), and joinsendpointBackfillRunnersand that test's list. Every connect, first or re-connect, user or system, runs the same sweep before enrollment (skipped when install just ran it) and, before the forwarder starts,asymptote.StageBackfillcopies the window'sharness.collection_method=polllines intocloud-backfill.jsonlbeside the runtime log, which thebeacon_backfillVector source (fingerprinteddevice_and_inode, so each atomically restaged copy is a new file) reads from the beginning into the runtime sink through the same privacy transform. Live hook/OTLP/plugin history before the connection point stays local. Re-connects restage, so a resend of already-shipped lines is expected and rests on the deterministicevent.id; a privacy-mode change clears the checkpoints and the restage renames the new-mode copy over the old one (kept until then so the copy is always a new inode; deleted instead when nothing restages), anddisconnectremoves it. System mode runs the collectors underwithUserHomefor the active console user (activeConsoleUser), with cursors under the system base directory, and reports a skip when nobody is logged in; root is reading a home the console user controls, so the sweep runs undersessionfs.Confine(anos.Rooton that home, files owned by the home's owner only, non-blocking opens that refuse FIFOs/devices, SQLite read from a private snapshot under<SystemBaseDir>/state/backfill-snapshots, retried until the database size/change counter and WAL header are unchanged across the copy, and refused pastsessionfs.MaxSnapshotBytes(512 MiB with its WAL) with the runtime's sync command named in the report), and refused paths read as absent and are listed in the report. User-mode sync and backfill stay unconfined. The wizard's confirm screen names the upload (WizardOptions.BackfillDays). Dry-run,--no-backfillandBEACON_BACKFILL=0skip all of it; the cmd tests run withBEACON_BACKFILL=0set inTestMain. beacon endpoint installhas a full-screen onboarding wizard on interactive user TTYs. It signs in, preselects Beacon Cloud, requires an explicit choice to opt out to Local, and asks Managed users to choose Standard or Metadata-only privacy. Signing in alone still moves no telemetry. Confirming Beacon Cloud does: the confirm screen states that it installs Beacon and starts forwarding, and names what the selected privacy mode sends, so that screen is the consent point. The managed destination is recorded only after enrollment succeeds, so a failed enrollment leaves a working local install, printsbeacon endpoint connectas the retry, and re-offers the question on the next install. The onboarding record is written only afterlifecycle.Installreturns, because a profile written first left a failed install looking onboarded and silently skipped the wizard on the retry. Explicitinstall --connectis unchanged. The wizard is skipped for system/root/CI/piped-stdin/dry-run orBEACON_ONBOARDING=0; those unattended paths must never gain an account or browser dependency. LegacyBEACON_ONBOARDING_EMAIL/USAGEsubmissions remain only for fleet compatibility. After the destination, the wizard shows an agent tools screen; every row is preselected (opt-out, space toggles). Beacon Cloud MCP is offered only with Beacon Cloud and runs thebeacon mcp connectflow (connectCloudMCPwithyes, OAuth, detected harnesses) only after the endpoint is connected (or already was), viafinishCloudSetup; a failed enrollment skips it and names the retry. The Beacon Agent Skills are offered for either destination and installed user-wide into~/.agents/skillsand, when Claude Code is set up,~/.claude/skills(cli/beacon/internal/agentskills,beacon skills install|uninstall; a.beacon-managedmarker decides what Beacon may replace or remove; install and repair refresh only copies Beacon already wrote). Both run afterlifecycle.Installreturns and warn rather than fail. The answers are recorded asonboarding.cloud_mcp/agent_skills. Implementation lives incli/beacon/internal/onboarding,cli/beacon/cmd/endpoint_onboarding.go,cli/beacon/cmd/endpoint_install.goandcli/beacon/cmd/agent_tools.go; keepdocs/cli/endpoint-onboarding.mdxanddocs/cli/skills.mdxin sync.- The update notice on bare interactive
beacon(cli/beacon/cmd/root.go, cache incli/beacon/internal/updatecheck/cache.go; docs indocs/cli/version.mdx) follows the Codex/Claude Code pattern: it reads~/.beacon/endpoint/update-check.jsonand never waits on the network, and only when that cache is a day old does it start a detachedbeacon version refresh(hidden) that asks GitHub for the latest release and rewrites the cache, failures included. It is the CLI's one background network call; it never runs from hooks, other commands, non-TTY output, CI or dev builds, andBEACON_UPDATE_CHECK=0turns it off. Installs other than Homebrew and the system package get the release download, becausebeacon endpoint updateapplies only to the system package. - Beacon Intel (client, request hardening, MCP tool specs and argument parsing in
pkg/asymptoteobserve/intelapi, shared with Beacon Cloud MCP so both servers offer one contract; the CLI's environment handling and the inventory-to-lookup mapping incli/beacon/internal/intel; the launch-command package parser and launcher registry config incli/beacon/internal/launchpkg, which the inventory scan runs so each MCP server record carriespackage/package_registry(the root system job runs it as the console user, in the hiddenbeacon endpoint inventory resolve-packageschild fromcli/beacon/cmd/endpoint_inventory_packages*.go, never with root's rights; config that exists but cannot be read makes the ecosystemprivate);cli/beacon/cmd/intel.go; docs indocs/cli/intel.mdx) reads the free public index athttps://intel.beacon.sh(theintel/app in ai-supply-chain-oracle, APIintel.v1:/api/v1/lookup,/artifact,/check,/status) so a person or agent can check an MCP server or skill before installing or running it. It needs no account and sends no token, key or telemetry: only what the caller names and the User-Agent. Only an explicitbeacon intelcommand or an agent's call to one of the local MCP server'sintel_*tools (cli/beacon/internal/mcpserver/intel_tools.go) reaches it; hooks, plugins and background jobs never do.intel_check_installedscans inventory in memory and sends only identifiersintel.FromInventoryreads from the scan: by default npm/PyPI packages from the public registries named in a server's launch command (cmd /cunwrapped; an unrecognized launcher option stops the parse rather than guessing which word is the package) and a skill's exact keyskill:<owner>/<repo>#<name>from the skills CLI's~/.agents/.skill-lock.json(never a lock beside a repository's own skills, which could claim any source; the repository may be private, and Intel keeps nothing it is asked), and only withinclude_private_namesthe names that may be private (configured server names, packages that may come from a registry or index other than the public one, as named by the command (--registry,--index-url, a config file), the server'senv/envFile, or what the launcher itself reads (launchpkg.LocalRegistries: inheritednpm_config_*/UV_*/PIP_*and the user, system and working-directory.npmrc,.yarnrc.yml,bunfig.toml,pip.conf,uv.toml,pyproject.toml; a private npm scope holds back only that scope), and the names of skills with no key); never paths, URLs, env or other args. A match made by name, including a package the index could only match by name, is markedname_only;dry_runsends nothing, and the tests assert no secret, path or argument reaches a request. Requests refuse redirects, cap the answer at 4 MiB, and accept only answers markedintel.v1.BEACON_INTEL=0turns it off andBEACON_INTEL_URLnames another host (https, or http on loopback). Everything printed from an answer goes throughtermLine(one line, no control or escape characters, bounded), and not found never reads as safe.pkg/asymptoteobserve/intelapi/contract_test.goruns the client against a real intel serving itstests/api/seed.sqlwhenBEACON_TEST_INTEL_URLis set; run it when either side changes a field. - Do not add dependency vulnerability scanning, OSV/GHSA lookups, package remediation, or other vulnerability-enforcement flows to the public hook path.
- Do not add broad runtime enforcement unless explicitly requested. Current control behavior is limited to hook-native approvals/denials exposed by supported agent runtimes.
- Keep destination support shaped like the existing local JSONL and customer-managed forwarding paths. Beacon may render supported packs or token-based endpoint forwarders, but should not add hosted SIEM dependencies or store third-party service credentials beyond the explicit supported configs. Elastic remains a file-tailing pack over local JSONL.
- Beacon writes retained prompt text, command output, raw tool inputs, raw OTLP attributes, and raw diffs to local or customer-controlled logs, subject to local redaction and size limits where supported.
- The Asymptote Observe TypeScript SDK may default to the hosted
/v1/observeendpoint as an opt-in cloud SDK contract. Beacon endpoint execution stays local-only/no-network.
Telemetry Scope
Supported runtime surfaces today:
- Claude Code and Codex CLI use local OpenTelemetry settings, and
beacon endpoint installwrites their user-level hooks alongside those settings (otlpTargetCarriesHookincli/beacon/cmd/endpoint_targets.go), because Claude's OTLP export has no session lifecycle, file activity, or subagent events and Codex's SessionStart hook supplies the OS-user context its spans lack. Both runtimes' Stop hooks record the turn's final reply fromlast_assistant_messageasagent.message(Codex through the dedicatedcodex-assistant-responsecommand, since its OTLP export carries no response text and it gets no generic hooks).beacon endpoint codex syncis the offline poll backfill from~/.codex/sessions; it never reads~/.codex/auth.jsonand cannot approve, deny, or delay tool calls. - Cursor hook telemetry for sessions, prompt submission, tool use, command execution, MCP-like tool activity, approval decisions, file edits, and agent reasoning (
afterAgentThoughtthinking text recorded asagent.reasoningevents in the OTel GenAIgen_ai.output.messagesreasoning-part shape) where hook payloads expose those fields. The Cursor IDE also runs the hooks in the user-level~/.claude/settings.json, with Cursor payloads; when Beacon's own~/.cursor/hooks.jsonruns the same hook subcommand and that entry's matcher selects the call's tool, that Claude Code run writes nothing and asks no policy provider (cursorRecordsThisHookincli/beacon-hooks/cmd/cursor_compat.go), so each event is recorded once. The two pre-tool matchers differ (Claude's names Read, Grep and Glob; Cursor's names Shell and MCP), so a call only Claude's matcher selects, a subcommand Beacon's Cursor hooks don't run, or a machine without them at the user level still gets the Claude Code run's record and policy check. While the desktop app shows a cloud agent it also runs the user-level hooks for that agent'safterAgentThought,subagentStartandsubagentStop(nothing else; measured on Cursor 3.29 and 3.30); a Cursor payload whose conversation id starts withbc-(the cloud agent) ortask-call-(its subagent) and that has noworkspace_rootswrites nothing outside a cloud sandbox (cursorRelaysCloudAgentincli/beacon-hooks/cmd/cursor_compat.go), so a cloud agent never reads as a partial local session; the cloud agent's own project hooks frombeacon cloud cursor print-hooksrecord it, including reasoning, replies and turn end. - Cline uses a Beacon-managed plugin (
~/.cline/plugins/beacon.ts) for live capture plusbeacon endpoint cline syncfor local history backfill. Cline's own OTel export/hosted prompt storage are not used, and approvals are not exposed or synthesized. - Pi-family runtimes use Beacon-managed extensions and the shared
cli/beacon-hooks/cmd/pi_family.gomapper while keeping separate harness names and install roots: Pi (pi_cli), Oh My Pi (omp), Prime Agent (prime_agent), and Senpi/OMO (omo_senpi). Pi, Prime, and Senpi do not expose operator approval decisions, so Beacon does not synthesize them. Oh My Pi exposes real approval events and the extension carries the remembered tool input onto those approvals. - Prime Agent is the Pi-family exception with a single persistent
ipythontool: kernel cells are recorded ascommand.executed, carry Python status/output metadata, and have no invented exit code. MCP is not separately attributed because Prime exposes integrations inside the kernel.beacon endpoint prime syncis the local poll backfill from~/.prime/agent/sessionsand session artifacts. - Senpi is the standalone OMO edition. The OpenCode and Codex editions ride existing Beacon integrations, so do not alias bare
oh-my-openagentto this extension. The install target isomo; the event harness isomo_senpi; agent-directory overrides follow OMO's own order (OMO_CODING_AGENT_DIR,SENPI_CODING_AGENT_DIR, thenPI_CODING_AGENT_DIR). - OpenCode uses the managed plugin for live capture and approvals, plus
beacon endpoint opencode syncfor current SQLite and legacy file-store backfill. Poll events are markedharness.collection_method=poll, cannot hold or deny tools, and must not synthesize approvals from persisted tool results. - Muse Code uses a Beacon-owned hooks file referenced by Muse
settings.jsonviamanaged_hooks_path. Muse Spark is the model, not the runtime; do not normalize Spark spellings tomuse_code.PreLLMCall/PostLLMCallstay unsubscribed because they carry full message arrays/tool schemas and chunked responses. - OpenHands hooks are merged into the runtime's own
.openhands/hooks.json. Project scope is the practical default because the loader takes the first hooks file and the CLI/GUI agent server reads the repository file. Approvals, token usage/cost, per-call tool ids, and assistant response text are not exposed or synthesized. - Kimi Code registers in the
[[hooks]]array of the runtime's own$KIMI_CODE_HOME/config.toml(default~/.kimi-code), the same file that holds[providers.<name>].api_key. Beacon appends its block and never re-serializes the document, and every write is parsed back and compared against the intended result before it replaces the file. Detection and removal go by the hook command rather than by Beacon's comment, because Kimi Code's legacykimi-climigration re-serializes config.toml and drops every comment. There is no project scope: Kimi Code reads one user-level config file. Thirteen of its twenty events are registered;SessionHeartbeatis deliberately left out because its sixty-second timer runs only when a hook is configured for it, andInterruptbecause Beacon's closing action asserts the agent finished. Kimi Code reports real operator approval decisions overPermissionRequest/PermissionResult, soPreToolUsemust not also synthesize one. Beacon writes nothing to stdout on this runtime, becauseUserPromptSubmitstdout is appended to the model's context; the policy seam denies with exit code 2 and is inert in the permission-request phase, which Kimi Code does not allow blocking. No token usage is exposed on any hook payload. - Kiro uses one Beacon-owned hook file under
.kiro/hooksor$KIRO_HOME/~/.kiro/hooks. Its hook stdout is added to agent context onSessionStartandUserPromptSubmit, so Beacon writes nothing to stdout on Kiro; blocking is exit code 2 with the reason on stderr. Approvals are not exposed or synthesized. - goose currently has only the adapter:
cli/beacon-hooks/cmd/goose.gocan map a manually writtenhooks.jsonthat invokesbeacon-hooks --platform goose, but there is nobeacon endpoint hooks install --harness goose, noDiscoverGoose, and no automatic OTLP configuration. Keep README/docs from implying goose is generally installable until those pieces exist. goose uses HTTP OTLP (4318), its blocking hook stdout must be{"decision":"allow"}or{"decision":"block"}, and it exposes no approval decisions or tool output. - DeepSeek Harness (
dsh) is installed through two user-level files:$DSH_HOME/beacon-endpoint-hooks.jsonand a row in$DSH_HOME/cordis.patch.yml; there is no project scope. The@deepseek-ai/dsh-hooks-claude-codebridge that row mounts is not shipped with the CLI (dev dependency only) and must be installed per profile with@deepseek-ai/dsh-hook-protocolat exactly the dsh version; a mount dsh cannot load is skipped at boot with only a warning. SoInstallDshfirst runshooks.InspectDshBridge(internal/endpoint/hooks/dsh_bridge.go, read-only: the installation found from thedshlauncher on PATH, each$DSH_HOME/profiles/*resolved Node-style, and rows in any patch layer that mount a bridge by absolute path at Beacon's hooks file) and returns*DshBridgeUnavailableErrorwithout writing anything when nothing loads a matching bridge; explicit--harness dshfails,--alland endpoint install skip with a warning. A healthy by-path mount (how Nix installs it; it must also resolve its declared dsh peers from its own location, because dsh's host-package interception applies only to profile plugins, elsepeers_missing) counts as installed and Beacon writes no row of its own (removing one it wrote earlier) so hooks never run twice. Beacon never installs the packages.DshStatus.Active/Bridge, discovery (misconfigured when inactive), doctordsh_hook_bridge, and inventory (each profile's patch layer) surface it; tests build on-disk fixtures withinternal/endpoint/hooks/dshtest. It also installs a Beacon-owned local skill at$DSH_HOME/skills/beacon-endpoint/SKILL.mdand supports native session backfill from$DSH_HOME/sessionsthroughbeacon endpoint dsh sync, which fills assistant text/reasoning, tool failures, and token usage that the hook bridge does not expose. It rides the Claude-shaped envelope on the hook path, butrun_coderemainstool.invokedbecause nested commands fire their own hooks. - fx (vercel-labs/fx) telemetry read from the session store fx commits under
~/.fx/sessions/, covering session start, prompts, tool calls, commands with exit codes and output, file reads/creates/edits with diffs, MCP tool calls, agent messages, history compaction, and per-turn token usage plus reported cost. fx exposes no third-party hook, plugin, or OTLP surface -- its lifecycle hooks are compiled into the binary -- so collection is a read of fx's own records, run bybeacon endpoint fx sync. Every event carriesharness.collection_method=poll; approvals are not synthesized (fx persists permission feedback text, not a per-call decision, matching the Cline and Pi posture) and no session-end event is invented, since fx sessions are resumable. Implementation lives incli/beacon/internal/fxsessionandcli/beacon/cmd/endpoint_fx.go. - Harness² (google-research/harness2) rollouts, read from the executor event streams Harness² records under its runs directory (
$HARNESS2_RUNS_DIR,~/harness2/runs, or a--runs-diran earlier sync was given and the cursor file remembers): OpenCoderun --format jsonand Codexexec --json, recognized by their first event rather than by file name. Harness² runs Codex under its ownCODEX_HOMEwith--ephemeraland OpenCode from a source checkout, so Beacon's Codex/OpenCode integrations do not record these sessions. Events carryharness.name=harness2,harness.collection_method=poll, the executor's own session id, and the rollout's benchmark/task/label/run/trial/attempt/harness fingerprint underraw.harness2. Codexturn.completedusage is the thread's running total and is differenced per turn; Codex exec lines carry no times, so they take the file's mtime. No prompts (an argv argument, absent from both streams) and no approvals are recorded or synthesized.testdata/recordedholds streams recorded from the exact OpenCode and Codex releases Harness² pins; re-record them when it bumps either. Implementation lives incli/beacon/internal/harness2sessionandcli/beacon/cmd/endpoint_harness2.go. - Antigravity CLI (
agy) conversation backfill, read from the transcripts Antigravity commits under~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/(transcript_full.jsonl;transcript.jsonl, whose tool arguments are JSON-encoded strings, only when the full one is absent) with the working directory, title, project and parent conversation fromconversation_summaries.dbbeside the brain directory (read throughsessionsync.OpenSQLite; a missing database or row means no working directory, not an error), bybeacon endpoint antigravity sync(aliasantigravity-cli,--brain-dir). Events carryharness.name=antigravity_cli,harness.collection_method=polland theconversationIdas the session id, the same id the live hooks write. Overlap with the hooks follows Devin CLI:CollectOptions.LiveCoverageis the earliestantigravity_clihook event per conversation in the retained runtime log the sweep writes to (integrations.HookCoverageincli/beacon/internal/endpoint/integrations, shared with Devin; computed by the sync command,--printincluded, and by the backfill runner, so install, connect and scheduled sweeps too), andsessionsync.LiveCoverage.Suppresses, also shared with Devin, drops for steps at or after it (two-second skew allowance)session.startedand every tool/command/file/MCP event, while prompts are dropped only when the hooks recorded one with the samecontent.hashin that conversation (LiveCoverage.RecordedPrompt, from the hook promptsHookCoveragecollects; a handoff link follows its prompt), because v1.3.60 hook blocks and a failedPreInvocationhook leave prompts unrecorded; Devin still drops prompts by time, keepingagent.message,agent.reasoningandtoken.usage, which the hook payloads never carry; suppressed events advance the cursor and are counted inevents_suppressed_live. Antigravity's prompt unwrapping, tool classification and tool path arguments areasymptoteobserve.AntigravityPrompt,AntigravityToolActionandAntigravityToolPath(pkg/asymptoteobserve/antigravity.go), read by both this collector and the hook adapter so the two paths classify a call the same way. Prompts are the text inside<USER_REQUEST>; planner responses yield reasoning, agent messages, onetool.invokedper call and per-response token usage (cache reads taken out of input); the nextGENERICsteps are those calls' results in order (Antigravity gives calls no id), withrun_command's exit code and output parsed from the result text.SYSTEM_MESSAGEsteps are skipped and no session end or approval is synthesized. Implementation lives incli/beacon/internal/antigravitysessionandcli/beacon/cmd/endpoint_antigravity.go. - Attribution of OTLP events: every account on a machine exports to the same loopback collector, and the exporter's base
useris the collector process's own account (asymptoteobserve.NewEventreads$USER/$USERNAME). On Linux, macOS and Windows the collector replaces it with the account that owns the sending socket (peer attribution):collector.ConfigYAMLrenders, only wherecollector.PeerAttribution(runtime.GOOSislinux,darwinorwindows), thebeacon_otlp_httpreceiver (collector-builder/exporter/beaconjsonexporter/otlphttpreceiver, the upstream OTLP/HTTP protocol rebuilt on confighttp soclient.Info.Addrkeeps the client port that upstream drops; it replacesotlp.protocols.httpon the same port and carries the sameinclude_metadataandloopback_hostauthenticator, so non-loopback Host headers are refused there too) and thebeacon_peerprocessor (peerprocessor, right aftermemory_limiterand beforebatch, which loses the connection) on Beacon's own pipelines, never the OTLP forward's, pluspeer_user: trueon beaconjson.beacon_peerremovesbeacon.peer.uid/beacon.peer.userwherever a sender put them (resource, scope, record, span, span event and link, every datapoint type), then asksinternal/peercredfor the owner of the client socket of exactly this connection: the client address fromclient.Info.Addrand the collector's end from the gRPC peer'sLocalAddror net/http'sLocalAddrContextKey(no server address, no lookup). On Linuxpeercredfirst asks the kernel with oneNETLINK_SOCK_DIAGexact four-tuple lookup (diag_linux.go, constant cost per export) and scans/proc/net/tcp{,6}for the same four-tuple when sock_diag itself is unavailable or, until sock_diag has once answered with a socket, when it says ENOENT (the kernel says that for a missingtcp_diaghandler too; a socket/procfinds then marks sock_diag blind for good); inode 0 (TIME_WAIT/orphan, uid printed 0), no match, or two owners are unknown, never guessed, and an unrelated TIME_WAIT on the same port is skipped. On macOS (peercred_darwin.go, parserpcblist.go, no cgo) it reads the wholenet.inet.tcp.pcblist_nsysctl table netstat reads (one read per export, proportional to the machine's TCP sockets) and takesso_uidfrom thexsocket_nof the pcb whosexinpcb_nis exactly the client four-tuple (IPv4 in the last four address bytes, IPv6 and v4-mapped in all sixteen; offsets from xnu's#pragma pack(4)structs, records walked by length and kind and padded to 8, a table without its closingxinpgenrefused); a pcb with no socket,SS_NOFDREF(closed by its owner), ort_stateCLOSED/LISTEN/TIME_WAIT is passed over even though xnu keeps the creator's uid there. On Windows (peercred_windows.go, parsertcptable.go)GetExtendedTcpTable(TCP_TABLE_OWNER_PID_ALL, AF_INET and, for an IPv4 pair too, AF_INET6 for v4-mapped rows; ports in network byte order) gives the owning PID of exactly the four-tuple, skipping PID 0/4 and CLOSED/LISTEN/TIME_WAIT/DELETE_TCB rows and client ends already closed (FIN_WAIT1/2, CLOSING, LAST_ACK, which can keep an exited process's PID); the process is opened (PROCESS_QUERY_LIMITED_INFORMATION), the table is read again and must still name that PID (a PID is not reused while a handle is open), and the answer is its token'sTokenUserSID. A user-mode Windows collector can open only its own account's processes, so other accounts' exports are unknown there. Byte-fixture tests for both parsers run on every OS; the live-socket tests (peercred_live_test.go) run only on macOS and Windows CI. The name comes frominternal/accountname(shared withbeacon_ingest). The converter reads the peer attributes from the resource only (mergeSignalAttrs), andapplyPeerUsercopies them intouseronly withOptions.PeerUser, and with it everyclaude_coworkevent, log, span or datapoint, has an emptyuser(applyPeerUser, which every signal passes through, andnormalizeClaudeCoworkContextfor logs; Cowork reaches a collector only through a relay such asbeacon endpoint cowork --ngrok, so the kernel names the relay's account, and the cloud identity is the sender's own claim; both stay in raw attributes; withoutPeerUserthe cloud identity still replaces the collector's account); thefalcon_hecexporter getspeer_user: truetoo, so LogScale matches the log; withPeerUseran unidentified sender gets an emptyuser, never the collector's root, so a recorded root always means root sent it. On macOS and Windows the config renders peer attribution only for a collector that lists the no-op marker extensionbeacon_peer_lookup(peerlookupextension, inbuilder.yaml, named by no config) inbeacon-otelcol components(collector.PeerAttributionFor,peerLookupMarkerRequired): older collectors already carrybeacon_peerandbeacon_otlp_httpwith a lookup that is unsupported there, andpeer_userwould leave their events with nouser, so a new CLI with one (--collector, a CLI-only upgrade, a repair before the collector is replaced) or with a collector that cannot list its components keeps the previous config.ConfigYAMLdecides from the binarycfg.Collector.BinaryPathresolves to, the one install, repair and the CI session check (ConfigYAMLWithPeertakes the decision explicitly); Linux needs no marker and is unchanged.CheckComponentsForrefuses a collector without both where they are rendered, from the same listing. A platform without a lookup (anything but these three) keeps the collector's account, as did macOS and Windows collectors before this (root, orCOMPUTERNAME$under LocalSystem). Hook and plugin events carry the person's uid or SID fromos/user.Current()(verified by the OS in restricted mode). The person is also on the session's hook and plugin events, joined bysession.id; the Sentinel guide carries the KQL. Peer attribution names the account that owns the sending socket, not necessarily the person who ran the agent (a relay, a shared service account, a process that inherited a socket), so never describe it as more than that. - Claude Cowork admin-configured OpenTelemetry setup guidance and local validation.
- OpenClaw Gateway uses a Beacon-managed plugin directory plus OpenClaw's own diagnostics OTLP guidance (
beacon endpoint integrations openclaw). The plugin'sbefore_tool_callhook is fail-closed, so the handler dispatches synchronously and returns without awaiting. Conversation hooks, includingllm_output, requireplugins.entries.beacon-endpoint.hooks.allowConversationAccess; without it, token and agent-message coverage is partial. Beacon reads OpenClaw JSON/JSON5 config for advice but does not rewrite it. - GitHub Copilot CLI uses MDM/customer-managed OTLP HTTP for live spans and approval-like activity, plus
beacon endpoint copilot syncto backfill local session records from~/.copilot/session-state. Poll events carry assistant text, complete tool results, command/file details, and token usage withharness.collection_method=poll, plus the shutdown's session-widetotalNanoAiudifferenced intogen_ai.usage.cost_usdonce per shutdown (10^9 nano-AIU = one AI credit = US$0.01), only for sessions started on or after the 2026-06-01 AI-credit cutover (cli/beacon/internal/copilotsession/cost.go); approvals still come only from the live OTLP path and are not synthesized from persisted records. - Runtimes that ride shared hook/OTLP paths without a special contract worth expanding here include Antigravity CLI (its session-store backfill is above), Devin CLI, Devin Desktop, Factory Droid, Gemini CLI, Grok Build, Hermes Agent, Qwen Code, and VS Code. Installed hook/endpoint support is governed by
cli/beacon/cmd/endpoint_targets.goplus the install/status switches incli/beacon/cmd/endpoint_hooks.go; discovery rows live incli/beacon/internal/endpoint/harness. - Browser chat telemetry through an optional MV3 extension (
browser-extension/; Chrome, with a beta Firefox build) covering claude.ai and chatgpt.com. A main-world interceptor tees the streamed response, a per-site adapter parses it into a normalized turn, and the service worker POSTs OTLP GenAI logs to the local collector on127.0.0.1:4318; the extension never writes files and never contacts a remote endpoint.harness.nameresolves toclaude_weborchatgpt_web(already handled byNormalizeHarnessNameinpkg/asymptoteobserve/harness.go, where the browser cases must stay above the genericclauderule) andharness.collection_methodisotlp. The one build serves every Chromium browser; each event names the browser it came from in the typeduser_agent.name/user_agent.versionfields (OTel semconv, promoted by the exporter so Metadata-only forwarding keeps them), resolved inbrowser-extension/src/shared/browser-identity.tsfrom UA Client Hints brands, with a UA-string fallback that also names Firefox. Scope is deliberately narrow: only those origins' chat streams, never other tabs or general browsing. Retention defaults tofull, so prompt and response text is retained by default; this is documented rather than defaulted down, because browser chat telemetry without content has no investigative value. Treat the adapters as experimental, since both sites' stream formats are private and undocumented. Per-browser differences live only inbrowser-extension/tools/targets.mjs(one entry per target, deriving its manifest fromsrc/manifest.json; Chrome ships that file verbatim todist/, Firefox getsdist-firefox/), and every extension API call goes through thesrc/shared/browser.tsshim (a unit test fails on directchrome.*use). The Firefox Gecko ID[email protected]is pinned and must never change. Managed fleets install a signed, self-hosted Chrome build instead of the unpacked zip: Chrome policy (ExtensionSettingsforce_installed) installs the CRX from theupdate_urlfeed (CHROME_UPDATE_URLintools/targets.mjs, also the manifest'supdate_url, dropped from the Firefox manifest), and the pinnedCHROME_EXTENSION_IDthere, derived from the CRX signing key, must never change either, because every fleet's policy names it.tools/pack-crx.mjssigns CRX3 files and writes the feed withnode:cryptoonly, so the signing job runs it withoutnpm ci. Admins lock settings through Chrome managed storage (src/managed_schema.json):getSettingsStateinsrc/background/settings.tslays those values over the stored ones on every read, each held toparseSettingsPatch, never writes them tostorage.local, and reports them aslocked, which the popup and options page show disabled andSET_SETTINGSrefuses to change. A managed-storage read that fails (anything but a missing area or Firefox's no-manifest refusal) setsmanagedError: nothing is captured, changed or delivered until it reads. Delivery (src/background/delivery.ts) applies the locks in force at send time (underPolicy): a locked endpoint retargets queued batches, and a locked-off site or capture, or a locked retention stricter than the batch was built with, drops them. A copy installed by policy (management.getSelf().installType === 'admin') holds delivery forPOLICY_GRACE_MSafter an install or update until Chrome delivers any managed value, because turns captured before then were shaped without the locks. beaconjsonOpenTelemetry Collector exporter that converts OTLP logs, traces, metrics, and resource attributes into Beacon endpoint JSONL.- OTLP forward (
beacon endpoint install|repair --otlp-forward-endpoint,--otlp-forward-protocol grpc|http/protobuf,--otlp-forward-harness, repeatable--otlp-forward-header,--no-otlp-forward;config.jsondestinations.otlp_forward): for machines whose runtimes already exported OTLP to another backend before Beacon pointed them at its collector. The collector renders anotlp/forwardorotlphttp/forwardexporter (both incollector-builder/builder.yaml) onlogs/forward,traces/forwardandmetrics/forwardpipelines fed by the same receiver:memory_limiter,beacon_forward_filter(forwardfilterprocessor; keeps only resources whose harness, resolved like beaconjson resolves it, is listed, default Claude Code and Codex, so browser-extension chats and other runtimes never leave),claude_api_bodyon logs,beacon_privacy,batch. The exporter's queue and retries are bounded so a down backend sheds data instead of pushingmemory_limiterinto refusing Beacon's own pipelines. It is a customer-chosen destination like the HEC exporters, not a Beacon network channel, and carries no hook or session-store data. Install and repair carry it over (buildConfig) until--no-otlp-forwardremoves it. Header values never go inconfig.json(ordinary accounts read the system one to find the system log): they live inOTLPForwardSecretsPath(otlp-forward-headers.json, 0600) and the 0600 collector config,config.jsonkeepsheader_names, and status, doctor andconfig showshow names only. Guide:docs/guides/kandji-otlp-forward-mdm.mdx. - Managed Microsoft Sentinel forwarder (
beacon endpoint sentinel forwarder install|status|remove --system, hiddenreconcile;cli/beacon/internal/endpoint/sentinel/forwarder.go,cli/beacon/cmd/endpoint_sentinel_forwarder.go; docs indocs/log-forwarding/microsoft-sentinel.mdx#vector-and-the-logs-ingestion-apianddocs/cli/sentinel.mdx): the bundled Vector (the MSI shipsvector.exebesidebeacon.exe, checked against the pinnedpackaging/vector/checksums bypackaging/windows/fetch-vector.ps1) run as a system service (BeaconSentinelForwarder,beacon-sentinel-forwarder.service,com.beacon.endpoint.sentinel-forwarder) throughservice.ForwarderManagerwith aForwarderSpec; the Asymptote forwarder's spec is the zero value, byte-identical units, and has no Windows service, soconnectstays refused there. System mode only. Its state is<SystemBaseDir>/forwarders/sentinel/(forwarder.jsonnon-secret settings,secrets.jsonread by Vector'sfilesecret backend, optionalclient.pfx,vector.tomlwith literal values,data/checkpoints,logs/vector-<date>.logwarnings),sysacl.SecureSecretDir/WriteSecretFile(root-only 0700/0600 on POSIX), apart fromconfig.jsonso repair never touches it. The credential is never a flag value (env or stdin). Install validates a scratch copy with Vector before writing anything, so a rejected install leaves the old forwarder. The config (pack/vector.toml.tmpl, shared with the manual env-var pack viamanualVectorConfig) readsruntime.jsonland.1with the default checksum fingerprint, acknowledgements on, a customretry_strategy(401/403/408/429/5xx, unlimited), 512 KB batches. Vector recognizes a file by its first line, so after the log is replaced with a copy (the log-access switch) it keeps reading the old file until restarted:lifecycle.Installtherefore reconciles withRestarton every install, repair and package upgrade (the macOS postinstall runs the hiddenreconcile), which is also how the MSI upgrade re-registers the service its uninstall step removed.lifecycle.Uninstallalways removes the service (sovector.execan be replaced) and keeps the state underKeepConfig; repair keeps it running (KeepForwarders).AZURE_AUTHORITY_HOST(--authority-host) goes into the service environment.sentinelmock(andcmd/sentinel-mock) stands in for Entra ID and the Logs Ingestion API;TestForwarderConfigDeliversThroughRealVectorruns real Vector against it inlinux-testandwindows-test(BEACON_TEST_VECTOR_BIN,BEACON_TEST_SENTINEL_TRUST_STORE=1on Windows), andpackaging/windows/smoke-sentinel-forwarder.ps1drives the installed MSI through setup, upgrade, log-access switches and uninstall inwindows-package-smoke. - Scheduled session sync (
beacon endpoint install|repair --session-sync,--no-session-sync;config.jsonsession_sync.enabled, opt-in; docs indocs/cli/endpoint-install.mdx#scheduled-session-sync): a one-shot job,com.beacon.endpoint.session-sync/beacon-session-sync.timer(service.SessionSyncManager), every 15 minutes starting one interval after load (jobSpec.runAtLoadfalse, unlike inventory: a run fired at load would take the sweep lock ahead of the install backfill that follows it), running the hidden-flaggedbeacon endpoint sessions sync --scheduled(cli/beacon/cmd/endpoint_session_sync.go), which isrunEndpointBackfill: the install backfill's sweep, window, budget and system-mode confinement, with cursors so each run reads only what is new.lifecycle.ReconcileSessionSyncJobinstalls it when on and removes it when off on every install, repair and package upgrade (beacon endpoint sessions install-daemon), andbuildConfigcarries the setting. It and the inventory job shareservice.scheduledJob(jobSpecper job). The scheduled run reports failures and exits 0 so the scheduler keeps it; a manual run fails on them. Every sweep (install, connect, manual and scheduled) and every writingbeacon endpoint <runtime> sync(throughcollectUnderSweepLock, once or per--watchtick; a test fails on a collector called directly fromcmd) holds<BaseDir>/state/session-sweep.lockfor its whole run, because collectors load cursors at the start and save them at the end; the scheduled run and watch ticks skip when it is held,--printtakes no lock, and the scheduled run returns early unlesssession_sync.enabledis on. An install or connect that skips its backfill (--no-backfill,BEACON_BACKFILL=0) records per-runtime floors insession-sync-floor.jsonbeside the lock (recordSkippedBackfill), and a session sync then reads only that runtime's sessions active since (sessionwindow.Recentis per session, so an ongoing one is read whole); only a runtime with none of its own cursor files (endpointBackfillRunner.State, resolved in the console user's home for a system endpoint) gets one, an existing floor is never moved later, a runtime added after the skip (no floor, no cursors) gets the earliest recorded floor, written to the file by the first session sync that sees it (floorRuntimesAddedSinceTheSkip) so it outlasts the cursors that sync saves, and a backfill that runs removes them all. A scheduled system run copies eachSQLiterunner's store at most everyendpointSnapshotInterval(an hour; times insession-sync-snapshots.json), because the confined copy can approachsessionfs.MaxSnapshotBytes. Tests pointendpointSweepLockPathat a temp dir inTestMain.beacon endpoint sessions enable|disable(lifecycle.SetSessionSync) changes only that key of config.json (setConfigFileKey) and reconciles the job, because a repair rebuilds the config from its flags and resets harnesses, ports and HEC destinations it is not given. Package installs set it withBEACON_SESSION_SYNC=1|0(unset keeps it) ininstall-endpoint.sh(macOS and Linux). A user-mode job carriessessionSyncJobEnv(the inventory job's variables plussessionSyncJobPathEnv/sessionSyncJobNameEnv), and a test fails when a session-store collector reads a variable it does not carry. - Endpoint inventory (
inventory.heartbeat/inventory.snapshotininventory_state.jsonl) is written by a scheduled job,com.beacon.endpoint.inventory(service.InventoryManager, user LaunchAgent or system LaunchDaemon,beacon-inventory.timeron systemd), every six hours and once at load, on by default and reconciled bylifecycle.ReconcileInventoryJobon every install, repair and package upgrade (beacon endpoint inventory install-daemon). Agent hooks do not trigger inventory any more; the hook binary's--cliflag andinventory-heartbeatsubcommand survive only as no-ops for hook commands written by older versions, andbeacon endpoint inventory heartbeat --trigger hookis likewise retired. A system-mode run inventories the active console user's home and still writes the liveness heartbeat when nobody is logged in; the scheduled scan has no working directory, so project-scoped config is only inbeacon endpoint inventory. - Beacon Cloud forwarding, the one Beacon-hosted network channel for endpoint telemetry: user-mode
beacon endpoint connectauthorizes device enrollment with the signed-in CLI account; system mode uses browser PKCE at/cli/enroll. Both store only the per-device key in<BaseDir>/asymptote/vector-secrets.json(0600, 0700 dir), render the selected privacy mode intovector.toml(re-rendered in place by install, repair and package upgrades, see above), validate it, and run Vector ascom.beacon.endpoint.asymptote-forwarder/beacon-asymptote-forwarder.servicethroughservice.ForwarderManager(refused in supervised mode).enrollment.jsonandconfig.json'smanaged_ingestblock carry only non-secret identity and privacy mode;beacon endpoint statusreports forwarder state and a live credential check (GET /v1/ingest/health, 3 s timeout);disconnectanduninstallremove the forwarder and credentials but never revoke server-side. - Asymptote Observe TypeScript SDK instrumentation for cloud applications, starting from OpenTelemetry/OpenLLMetry patterns and
observe()wrappers. - Elasticsearch/Filebeat content pack generation for forwarding local Beacon JSONL into customer-managed Elastic deployments or the bundled loopback-only development stack.
- A local-only dashboard served by
beacon endpoint dashboard, bound to loopback by default and backed by the runtime JSONL log (docs indocs/cli/dashboard.mdx#access-control). Loopback binding andRequireLoopbackHostkeep other machines and DNS-rebinding pages out but not other local accounts, so every run (andbeacon lenses preview) makes a per-launch secret (dashboard.NewToken, 256 bits, kept in memory and printed only insideLaunchURL's?token=, never written to a file, log or JSON) andListenAndServerefuses to start withoutOptions.Token.RequireToken(dashboard/access.go) accepts the token once per browser, sets an HttpOnly, SameSite=Strict, Path=/ cookie named for the port (CookieName) and 303-redirects without the token; every other request needs the cookie (constant-time compare) or gets 401. Lens frames and/api/lens-dataride the cookie as same-site requests; the e2e server takes its secret fromBEACON_E2E_DASHBOARD_TOKENand the Playwright config seeds the cookie (tests/access.spec.tscovers the launch URL). Cookies are shared across ports of127.0.0.1, so never describe the secret as more than keeping out accounts that do not have it. The administrator switch is the systemconfig.jsondashboard(enabled, the default when empty, ordisabled;install|repair --system --dashboard,BEACON_DASHBOARDin the three install scripts, carried bybuildConfig, refused in user mode; an unattended first package install (the same no-system-config-and-no-log test as restricted log access, and no person by the same test asBEACON_LOG_READERS: LinuxSUDO_USERat a controlling terminal, macOS Installer.app, MSIUILevel>= 4) passesdisabledwhenBEACON_DASHBOARDis unset, on every platform and service mode; a person's own install and upgrades pass nothing): when disabled,refuseDisabledDashboard(cmd/endpoint_dashboard_access.go, viaendpointconfig.SystemDashboardDisabled) stops the dashboard and lens preview for every account, and status reports it asdashboard. Any value but empty orenabledreads as disabled (Config.DashboardMode), andbuildConfigcarries such a value asdisabled(carriedDashboard) so preflight never fails a repair over it. A system config holding a HEC token is root-only, soendpointconfig.Savealso keeps a world-readabledashboard-disabledmarker beside the system config while the switch is off (syncDashboardMarker; uninstall removes it);DashboardDisabledAtreads the config when it can and the marker only when reading the config is refused for permission, a config that does not parse refuses, andbuildConfigkeeps the switch off from the marker (systemDashboardMarked) when the config does not load. - Token usage and runtime-reported cost capture across spans, logs, and metric datapoints, normalized into
gen_ai.usage, with attribution rollups served by the dashboard token view (/api/tokens) and thebeacon token-usagereport command for local and CI logs. Every report row carries three costs (cli/beacon/internal/tokens/cost.go):cost_usd(runtime-reported, unchanged),estimated_cost_usd(list price of every priced token, frominternal/pricing, computed after dedup and cumulative resolution) andeffective_cost_usdwithcost_source(per endpoint/harness/session scope, reported cost wins wholesale when the scope has any; otherwise the estimate; session-less events per event), plusunpriced_events/unpriced_tokensand a report-levelpricingblock (catalog provenance, per-model key, match, base rates, bands applied, fallbacks, unpriced models). Long-context bands apply only to eventsrequestScopedclassifies as one model request; it defaults to aggregate, so a new capture path is priced at base rates until it is added there with a test. Lens data (LensDataV1) carries no estimate. - Local threat detection via
beacon scan, which runs the open Threat Rules format (spec/threat-rules; CEL match conditions over the endpoint event schema, with embedded conformance fixtures) over the runtime JSONL. The engine (pkg/asymptoteobserve/threatrules) ships in the binary; the rule corpus is external data loaded from a local store (~/.beacon/endpoint/rules) managed bybeacon rules, so the corpus can grow without enlarging the binary.scanis read-only and offline; only the explicit, user-initiatedbeacon rules pull <url>reaches the network, overhttps://only (plain http just for loopback, no redirect off https), size-capped, and verified first when--sha256is given. A small frozen baseline is embedded soscanworks before any rules are installed, and it stays active alongside the store: a store rule replaces a baseline rule only by id (rulestore.LoadActiveSkipping), so installing one rule never silently switches the baseline off; only--rules <dir>runs a directory alone. - Session handoff via
beacon handoff list|export|resume(cli/beacon/internal/handoff,cli/beacon/cmd/handoff*.go; docs indocs/cli/handoff.mdxanddocs/concepts/session-handoff.mdx). Every runtime is one entry in the registry incli/beacon/internal/handoff/runtimes.go: its session source, the names it answers to, and the commands that reopen it or start it from a brief;TestRegistryIsConsistentchecks the entries. Handoff reads the session stores of Claude Code, Codex CLI, OpenCode, Cline, Pi, Prime Agent, Factory Droid, GitHub Copilot CLI, Hermes Agent, DeepSeek Harness, fx, Grok Build, OpenClaw Gateway and Cursor read-only and never touches the network. Oh My Pi, Gemini CLI, Qwen Code, Kiro, Antigravity CLI, Devin CLI, Muse Code, OpenHands and goose have no store Beacon reads: their sessions come from the runtime log, and they take a brief as the target of--agent.resumereopens a session natively with its runtime's own command when it can, and otherwise writes a brief to~/.beacon/endpoint/handoffs(0700/0600) and starts a new session pointed at it. DeepSeek Harness cannot be started, and Hermes Agent and fx only reopen their own sessions, so their sessions continue in another runtime. fx, Grok Build and Cursor find a session by the directory they run in, so they are reopened natively only in the session's own directory. The brief is passed by absolute path, never inlined on a command line. By default the runtime runs in the calling terminal;--launch auto|new-terminal|tmux(internal/handoff/detached.go) instead writes a one-timelaunch-<id>.jsonspecification (0600, expires after five minutes) beside the briefs, opens a terminal surface (cmux or Terminal.app, Windows Terminal or PowerShell, a Linux terminal emulator, or a detached tmux session) running the hiddenbeacon handoff _launch --spec, and waits up to 15 s for it to confirm the runtime started, removing the specification on a timeout so a late terminal starts nothing (the trampoline claims it by an atomic rename, so a timeout after the claim reports that the runtime may still start rather than cancelled, and the status is renamed into place so the caller never reads it half-written). Content is never put on the terminal's command line, and only the store-locating path variables incarriedEnvNames, never credentials, are carried into the specification. Every launch keeps the runtime's approvals on: Beacon never passes a flag that turns them off, names the approval mode that asks where a CLI takes one (Cline always gets--auto-approve false, because Cline defaults to approving every tool call), and removes or overrides environment switches that would approve everything (COPILOT_ALLOW_ALL,COPILOT_PLAN_THEN_AUTOPILOT,HERMES_YOLO_MODE,GOOSE_MODE);--printshows them underenv. Briefs run every event throughSanitizeEvent, and quoted content goes in fences longer than any backtick run it contains, with inline fields reduced to one line, so quoted content cannot forge brief structure. A new session's first prompt ends with the[beacon-handoff from=<harness> session=<id>]marker (pkg/asymptoteobserve/handoff.go). The hook and plugin prompt paths and the session-store mappers record asession.handoffevent withhandoff.{source_harness,source_session_id}when they see it; that is an observed claim, not a verified identity. - Session sharing via
beacon shareandbeacon share refresh(cli/beacon/cmd/share.go; docs indocs/cli/share.mdx, with the workflow guides indocs/sharing/kept in sync). It publishes one session the person names (or the most recent in a directory) to beacon.sh as a shared trace that is abeacon.trace.v1trace, the projection the dashboard uses:BuildShareBundle(sanitize, scrub, thenTraceEventFromEvent/TraceBuilder), the wire types (ShareTraceV1summary body,ShareEventsBatchV1ofTraceEventV1s,ShareTraceStateV1withlast_event_id),ShareExternalID(<harness>:<session-id>, or a sha256 form),ShareRelationandShareEventsAfterlive inpkg/asymptoteobserve/share.go, and the client incli/beacon/internal/account/share.go(PUT /v1/traces/{external_id},POST .../events/batchcapped atShareMaxEventsPerBatch,GET). The chat view is derived on beacon.sh withTraceMessages(pkg/asymptoteobserve/tracemessages.go), which pairs a tool invocation and its completion bytool_call_idand writes a call reported twice once; messages are never uploaded. Sessions resolve through the handoff registry (store first, then the runtime log). Every event goes throughSanitizeEventand session-directory/home paths are rewritten in every projected field before projection, and the shared summary drops the working directory and repository path and names the project byproject.name.--printshows the exact{external_id, trace, events}payload with no network,publicneeds confirmation (refused without a terminal unless--yes), a re-share upserts by stable event id, and a refresh sends onlyShareEventsAfterthe server'slast_event_id(re-sending it and any tool call still open). After an upload it writes onesession.sharedevent (event.fidelity=inferred, no collection method) carryingshared_url,visibility,shared_at/last_refreshed_atin raw, which the trace list reads as the sharing state; the projection skips that event. It never runs from hooks or in the background, except the opted-in pre-push sharing below. From a Metadata-only endpoint the share payload goes throughasymptoteobserve.StripToMetadata(the same fields the Vector metadata transform removes, applied after event ids are derived) and drops the derived title. With no selector (or--current) it shares the session it runs inside:BEACON_SESSION_ID/BEACON_HARNESS(the Claude Code SessionStart hook appends both asexportlines to$CLAUDE_ENV_FILE, plain identifiers only; a child runtime inherits them, so without--harnessthey are refused, naming both sessions, when the named session ran outside this directory and its parents or another runtime worked here more recently:shareEnvContradiction), then the active-session record (only when the entry was seen at least as recently as the directory's newest session, since OTLP-only and poll runtimes never write it), then the directory's most recent session. The record ispkg/asymptoteobserve/activesession(~/.beacon/endpoint/active-sessions.json, 0600 under 0700, atomic and locked, at most 256 entries, 14-day prune, an unchanged entry rewritten at most once a minute), written by the hook logger after every endpoint event with a session id, working directory and harness; it holds identifiers and paths only, never content, and hooks write it silently and never touch the network for it. Hook tests pointBEACON_ACTIVE_SESSIONS_FILEat a temp file inTestMain. Auto-share (beacon share auto enable|disable|status,cli/beacon/cmd/share_auto.go, settings inpkg/asymptoteobserve/shareauto) is server-side publishing: when it applies to a session's working directory, the hook logger writes ONE localsession.share_requestedevent per session (event.fidelity=inferred,share.visibility; deduplicated under the active-session record's lock) and Beacon Cloud forwarding ships it; beacon.sh builds and refreshes the trace with the sameBuildShareBundleprojection andShareExternalID. Hooks never upload. The user file~/.beacon/endpoint/share.json(0600, CLI-written) holds the user-wide switch, three-state (unset, on, or off as a kill switch over every project;auto.state, withauto.enabledkept in step so older files read) and per-project choices by path, which a user-wide enable or disable never rewrites; a project marker<repo>/.beacon/share.jsonmay disable on its own (and an off marker wins over the user's entry for the same directory; the closest directory with an entry or marker decides) but enables only when the user's file trusts that project, with the user's visibility, so a cloned repository can never publish someone's sessions.ForHookcosts one failed read when nothing is enabled. Hook tests pointBEACON_SHARE_SETTINGS_FILEat a temp file. The share projection andhandoff.LogSessionsrecency skipsession.share_requested. - Commit-to-session links via
beacon git setup|status|remove|link|notes(cli/beacon/internal/gitlink,cli/beacon/cmd/git*.go; docs indocs/cli/git.mdx). A link is abeacon:<harness>/<session-id>line in a git note underrefs/notes/beacon; it carries identifiers only, never content, because notes can be pushed. Which sessions to link is inferred from the local runtime log: a session is linked when, between the parent commit and the commit (at least two hours, at most 24), it wrote a file the commit changes (for a merge, only files that differ from every parent, so a clean merge or pull links nothing). Evidence is file write events, write-typefile.operations, plainly readable shell targets, andapply_patchenvelopes; reads never count. Note updates are a compare-and-swap on the notes ref through a privaterefs/notes/beacon-tx/working ref, and every existing note line, a teammate's or a person's, is kept verbatim.setupinstalls post-commit (links HEAD in the foreground with a 3 s budget, silent, never fails the commit, skips rebase/cherry-pick/revert) and post-rewrite (normalizes the note git concatenates on amend) as standalonebeacon-<hook>scripts called from a marked block inserted after the shebang of the repository's own hook; only shell hooks are edited,core.hooksPathis refused without--hooks-path, andnotes.rewriteRefcarries links through amend and rebase.BEACON_GIT_HOOKS=0disables the hooks for one command. Every link a run adds is also written to the runtime log as onesession.commit_linkedevent in the linked session's timeline (event.fidelity=inferred, no collection method), with commit id, branch and credential-stripped remote in the OTel-shapedvcsblock and overlap counts invcs.attribution; the event deliberately carries no file, command or tool fields so it can never become attribution evidence. Sharing is opt-in (setup --share-notes, off by default): a non-destructive fetch refspec+refs/notes/beacon:refs/notes/beacon-remotes/<remote>so git's own fetch brings teammates' links into a read-only tracking ref thatbeacon git notesunions with the local one (never force-fetch intorefs/notes/beacon: it would destroy unpushed links), and a pre-push hook that fetches, merges withcat_sort_uniqthrough the same CAS, and pushes only the notes ref with--no-verify, within a 10 s budget and never failing the push. That pre-push hook is the only Beacon git hook that touches the network, and only during a push the person started;beacon git notes push|fetchdo the same by hand. A note line may carry the session's share URL as its first trailing field (beacon:<harness>/<id> <url>; an identifier, not content):gitlink.ValidShareURLadmits only https URLs on beacon.sh or the configured Beacon host (AllowShareHost, fed bygitAllowShareHosts), on write and on read, andMergeNote/ParseNoteprefer the line with the URL over the bare one. Post-commit andlinktake URLs only from localsession.sharedevents (localShareURLs).setup --share-sessions [--share-visibility](implies--share-notes; stored asbeacon.shareSessions/beacon.shareVisibilityin local git config; public needs confirmation or--yes) makes the pre-push hook, which now receives git's stdin, share sessions linked to pushed commits that have no URL (at most 100 commits/10 sessions, silent without credentials, never failing the push; the budget is enforced by the clock: the share phase runs in a goroutine delivering URLs to a collector, the hook takes what it holds after the 6 s upload budget and abandons the rest, then writes notes and pushes the notes ref with what remains of the hook's 10 s, never less than 1 s and 3 s, so only the main path ever writes notes) throughshareUpload(cmd/share_upload.go:alignShareSource+ShareEventsAfter), then write the URLs into the notes before pushing them.beacon share --follow [--interval](cmd/share_follow.go) polls the session locally, uploads throughshareUploadonly when the fingerprint of the projected trace events changed (the events only: the trace body carries its build time), stops atsession.endedor Ctrl+C (shareFollowWait/shareFollowSignalsare the test seams), and recordssession.sharedafter each upload, later ones as refreshes that keep the share date;docs/cli/share.mdxcarries the API-key CI walkthrough with GitHub Actions and GitLab CI examples. Local views show sharing read-only: the trace summary (traceFold, which wrapsasymptoteobserve.TraceBuilderwith the local-onlytraceStaleness, and the history throughtraceAggregateState, derivation version 12) and the dashboard'sSessionRecord.Sharingmark a shared sessionstalewhen an eventasymptoteobserve.ShareProjectsaccepts (the one definition of what a share publishes) and that is not the share's own (shareActivity) is newer than what its lastsession.sharedrecord covered (shared_through), and carryasymptoteobserve.ShareRefreshCommandfor the reader to copy; the session list/page,beacon tracesTUI and plain list display them, and nothing in them shares. - Beacon Cloud MCP registration via
beacon mcp connect|disconnect|status(cli/beacon/internal/mcpconnect,cli/beacon/cmd/mcp_connect.go; docs indocs/cli/mcp-connect.mdx). It registers the Beacon Cloud MCP server asbeacon-managed, a different name from the local stdio serverbeacon, in the user-level config of Claude Code, Codex CLI, Cursor, VS Code, Gemini CLI and OpenCode. It prints manual steps for runtimes without confirmed MCP OAuth support. OAuth is the default and writes only the URL;--token-envwrites a reference to an environment variable in each harness's own syntax, never a value.connectnever reads or copies the account token and never writes a token; minting one is the separate, explicitbeacon mcp token create. It is explicit and interactive: never run by an unattended install; the onboarding wizard runs it only after the person chose Beacon Cloud and left "Beacon Cloud MCP" selected (that screen is the confirmation), and otherwise the install only suggests it. It is refused as root, and refused in CI or without a terminal unless--yesis given. Its one network request is the RFC 9728 resource-metadata check of the URL, which--dry-runskips. Configs are edited like the Kimi Code writer: never re-serialized, spliced as text, parsed back and compared before an atomic replace, backed up first. What was written is recorded in~/.beacon/mcp/connections.json, anddisconnectremoves only entries recorded there that still point at the recorded URL.cmd/mcp_connect_e2e_test.goruns the real harness CLIs when they are installed; re-run it when a harness changes its MCP config format. - An optional, off-by-default policy seam in the hook path (
cli/beacon-hooks/internal/policy) governed by the stable contract inpkg/asymptoteobserve/policycontract. WhenBEACON_POLICY_PROVIDERnames an executable, thepre-toolandpermission-requesthooks send it a JSON request describing the imminent tool call and honor an allow/deny response, returning the runtime's native deny shape andpolicy.enforcement=enforcetelemetry on a deny. The seam is inert when unset and fail-open on any error (timeout, non-zero exit, malformed output), so the open build ships no enforcement of its own; all audit/enforce decision logic lives in the external provider.rules/agent-control/agent-permission-bypass-spawn.rule.yamlis the open detect twin that flags the same pattern inbeacon scan.
Current non-goals unless explicitly requested:
- Kernel/process monitoring, EDR replacement, shell history scraping, cloud audit ingestion, general browser or SaaS activity monitoring beyond the supported chat surfaces, credential-use attribution, and MCP configuration inventory.
- Direct hosted integrations for Datadog, Snowflake, Chronicle, Panther, or other SIEM destinations beyond explicitly supported local/customer-managed forwarding patterns and the opt-in Asymptote Managed path.
- Dependency vulnerability scanning or package security remediation.
Common Commands
Run tests for the public CLI. Build the embedded hooks binary first — several tests require a real one and fail against the checked-in placeholder:
cd cli/beacon
make build-hooks-current
go test ./...
go test -race ./internal/endpoint/...
Run hook adapter tests:
cd cli/beacon-hooks
go test ./...
Run packaging wrapper checks:
sh packaging/macos/test-endpoint-scripts.sh
Run the macOS endpoint smoke test:
sh packaging/macos/smoke-endpoint.sh
Build the CLI:
cd cli/beacon
make build
Run Collector exporter tests:
cd collector-builder/exporter/beaconjsonexporter
go test ./...
Run the observe SDK and threat-rules conformance tests:
cd pkg/asymptoteobserve
go test ./...
Run the Terraform module tests (the providers are mocked, so no cloud account is needed):
for module in terraform/*/; do (cd "$module" && terraform init -backend=false && terraform test); done
Run the managed runtime plugin/extension checks (each verifies the checked-in copy matches its embedded twin, then runs its tests):
cd plugins/shared && bun run check && bun test
cd ../opencode-beacon && bun run check && bun test
cd ../cline-beacon && bun run check && bun test
cd ../pi-beacon && bun run check && bun test
cd ../omp-beacon && bun run check && bun test
cd ../openclaw-beacon && bun run check && bun test
cd ../prime-beacon && bun run check && bun test
cd ../omo-beacon && bun run check && bun test
After editing a plugin or extension source, run bun run sync in its directory to update the
embedded copy under cli/beacon/internal/endpoint/hooks/assets/; a Go test fails if the two drift.
openclaw-beacon syncs three files rather than one, because OpenClaw discovers a plugin as a
directory: the entry plus the two manifests it is declared in.
The payload serializer (safeClone and its maxDepth) has one source, plugins/shared/safe-clone.ts.
Every plugin except OpenCode carries a generated copy between // BEGIN shared/safe-clone and
// END shared/safe-clone, because each installs as one self-contained file and cannot import it.
Edit only the shared file, then run bun run sync in plugins/shared to rewrite every plugin source
and embedded copy (OpenClaw's .js copy has its two type annotations stripped). Each plugin's
bun run check and plugins/shared's tests fail when any copy differs.
Run the lens sandbox browser tests (the real dashboard plus hostile fixture lenses; the hooks
binary must be built first). In a cloud session with a preinstalled Chromium, set CHROMIUM_PATH
instead of installing one:
cd cli/beacon && make build-hooks-current
cd internal/endpoint/dashboard/testdata/lens-e2e
npm ci
npx playwright install chromium # or: export CHROMIUM_PATH=/path/to/chromium
npx playwright test
Run TypeScript SDK checks:
cd packages/asymptote-sdk-js
npm test
npm run check
npm run build
npm run pack:dry-run
Run browser extension checks. The e2e replays recorded SSE through the real
extension in headless Chromium, so it needs openssl on PATH and a one-time
Chromium download, but no login and no network:
cd browser-extension
npm ci
npm run check
npm run test:unit
npx playwright install chromium # one-time
npm test # builds dist/, runs the replay e2e
Exercise the goose adapter during manual testing. There is no --harness goose installer yet (see
the goose entry under Telemetry Scope), so the hooks file and the OTLP endpoint are written by hand
and only the payload mapping can be run from the repository:
cd cli/beacon-hooks
go test ./... -run Goose
Collect fx session telemetry during manual testing:
cd cli/beacon
go run . endpoint fx status # sessions fx has written and how much Beacon has read
go run . endpoint fx sync --print # map records to events without writing anything
Collect Antigravity CLI conversations the same way (--print never writes the runtime log):
cd cli/beacon
go run . endpoint antigravity status
go run . endpoint antigravity sync --print
Connect an endpoint to Asymptote Managed during manual testing (needs Vector 0.50+ on the machine;
/opt/beacon/bin/vector from the signed package works, and a browser signed in to an org that has
managed ingest enabled):
cd cli/beacon
go run . endpoint connect # browser approval → device key → forwarder service
go run . endpoint status --json | jq .managed_ingest
go run . endpoint disconnect # stop the forwarder and remove the local key
Run the Asymptote Managed forwarder by hand instead (a device key from beacon-ingest/scripts/mint_test_device.py
or a previous connect):
cd cli/beacon
go run . endpoint asymptote install-pack --output /tmp/beacon-asymptote-pack --log-path "$HOME/.beacon/endpoint/logs/runtime.jsonl"
BEACON_ASYMPTOTE_INGEST_URL=https://<ingest> BEACON_ASYMPTOTE_SECRETS_FILE=/path/to/secrets.json BEACON_ASYMPTOTE_DATA_DIR=/tmp/beacon-asymptote-data \
vector validate --skip-healthchecks /tmp/beacon-asymptote-pack/vector.toml
go run . endpoint asymptote validate # writes a validation event the forwarder ships
Run the local dashboard during manual testing:
cd cli/beacon
go run . endpoint dashboard
Run local threat detection and manage rules during manual testing:
cd cli/beacon
go run . scan # run active rules over the runtime log
go run . rules list # show active rules (store plus baseline)
go run . rules lint ../../rules # validate + run the repo rule pack's fixtures
When adding event fields a rule can match on, regenerate the field reference:
beacon rules fields --markdown > spec/threat-rules/FIELDS.md (a conformance test fails if
it drifts).
Release Deployments
Homebrew releases are published by GoReleaser from cli/beacon/.goreleaser.yaml.
Prefer a CI-based release workflow triggered by an annotated version tag. Use a
local GoReleaser publish only as a fallback when CI release automation is not
available or the maintainer explicitly asks for a local release.
A pushed v* tag runs the full release end-to-end via
.github/workflows/release.yml (no local publish steps required), in five jobs:
goreleaser(ubuntu,environment: release) builds the collector dists, publishes the GitHub release + changelog and tarballs, and updates the Homebrew tap. When theBEACON_LINUX_SIGNING_KEYsecret exists, nfpm signs the.deb/.rpmwith it, and GoReleaser'ssignsentry signschecksums.txtaschecksums.txt.sigand attaches the public key (beacon-release-key.{asc,gpg}, staged by the workflow undercli/beacon/release-key/). GoReleaser uploads into a draft and publishes last, so a pinned installer never sees a latest release without its.sig. Without the secret the workflow passes--skip=signand they ship unsigned. It then attests the.debfiles from its owndist/(signed, when the key exists) withactions/attestand this repository's predicate type (.../attestations/goreleaser-deb/v1), which the apt repository requires (id-token: write,attestations: writeon that job). The step iscontinue-on-error, because the release is already published by then: a failed attestation fails only the apt job, never the.pkg, MSI or finalize.package(macOS,needs: goreleaser,environment: release) builds the Apple Siliconbeacon/beacon-hookspackage payload plus arch-matched collector and Vector binaries fordarwin_arm64, then signs, notarizes, staples, and uploads the.pkg,.sha256, andupdate-manifest.json. GoReleaser still publishes multi-arch CLI tarballs; the signed endpoint.pkgis arm64-only so it can carry a current Vector release.windows-package(windows-2025,needs: goreleaser) builds the x64 MSI from the published archive plusvector.exe(packaging/windows/fetch-vector.ps1, checked against the same pinnedpackaging/vector/checksums; the Windows zip itself carries no Vector), installs and uninstalls it on the runner to prove it works, and attaches the.msiand its.sha256. Deliberately not in thereleaseenvironment: that environment gates signing secrets, and the MSI is unsigned, so this job has none to gate.finalize(ubuntu,needsgoreleaser, package and windows-package, runs whenevergoreleasersucceeded) appends the.pkg,.msiandinstall.shtochecksums.txtfrom the released bytes and records a GitHub build-provenance attestation (Sigstore, keyless, through the workflow's OIDC token) for every filechecksums.txtlists. It needsid-token: writeandattestations: write, and runs in thereleaseenvironment only so that, whenBEACON_LINUX_SIGNING_KEYexists, it can sign the extendedchecksums.txtagain before uploading it; a failure before that leaves GoReleaser's matching pair in place. GitHub replaces assets one at a time, so it uploadschecksums.txtthen its.sig, reads both back and re-uploads until the published pair is what it signed, and fails loudly otherwise;install.shand the self-updater fetch the pair once more before refusing a signature that does not verify, which covers the seconds between the uploads. Anything else that rewriteschecksums.txtmust come before that step.apt-repository(ubuntu,needs: goreleaser,environment: release,contents: read/attestations: read) adds the released.debfiles to the signed apt repository (deb <APT_REPO_URL> stable main) in an S3-compatible bucket, because 85-90 MB packages outgrow a git-backed Pages repo.packaging/linux/apt/build-apt-repo.shreads back only the published index (InRelease, and eachPackagesthrough the by-hash path it names, so a publish that stopped partway reads consistently and resumes), verifies it against the committed public keyspackaging/linux/apt/beacon-archive-keyring.ascbefore re-signing (so an edited index is never re-signed), refuses to replace a published version, and fails unless every key in the secret is a committed one and signed. Every.deb(this tag's and each backfilled one) must passgh attestation verify --predicate-typeagainst the goreleaser job's attestation of the bytes it built, fromrelease.ymlatrefs/tags/<tag>. Never the release's replaceablechecksums.txt, and never finalize's provenance, which re-hashes those same replaceable assets and whose job re-runs without approval. It is pinned (--source-digest/--signer-digest) to the tag's commit, which must be an ancestor of this run's commit: anyone who can push av*tag can run their ownrelease.ymland mint an attestation for that path and ref, so only packages built from this release's history are trusted (the checkout usesfetch-depth: 0for the check). Its control fields must namebeacon, the tag's version and the architecture; this tag's must pass, and a backfilled one that fails (no attestation, or a tag outside the history) is left out with a warning. Rotating the key is a reviewed commit in two steps: commit the new public key beside the old and put both secret keys inAPT_GPG_PRIVATE_KEY, so every release is signed by both and hosts that trust only the old key keep updating while they fetch the new keyring; then remove the old key from the file and the secret. Hosts install the keyring once and the package does not ship it, so one that never refetches it breaks at step two. A published index counts as signed with at least one good signature from a committed key and no bad one. First publish is decided by ahead-objectondists/stable/InRelease(404 only; any other error fails). Each run adds its own tag plus any of the lastAPT_BACKFILL_RELEASES(10) stable releases up to it that the index lacks, because theapt-repositoryconcurrency group cancels a pending job when a third arrives; that also repairs an index rolled back in the bucket within the window.verify-apt-repo.shruns a real, isolatedapt-get update/downloadagainst the staged tree (the index, then each staged package by its own version and architecture, since the tree holds only what the run adds) and again against the public URL for the tag's version; CI'sapt-repositoryjob runstest-apt-repo.sh. Upload order is pool, index, thenRelease.gpg/Release/InReleasewithAcquire-By-Hash. Skipped with a notice until everyAPT_*setting exists, and for prerelease (-) tags.
Every third-party action in release.yml, release-extension.yml and
npm-publish-sdk.yml is pinned to a full commit SHA with the version in a
trailing comment, because these jobs hold the signing secrets or, for the SDK,
the id-token npm's trusted publisher accepts. Bump them by SHA, never back to
a tag.
Required release-environment secrets: HOMEBREW_TAP_TOKEN,
DEVELOPER_ID_APP_CERT_P12, DEVELOPER_ID_APP_CERT_PASSWORD,
DEVELOPER_ID_INSTALLER_CERT_P12, DEVELOPER_ID_INSTALLER_CERT_PASSWORD,
NOTARY_API_KEY_P8, NOTARY_API_KEY_ID, NOTARY_API_ISSUER; plus Variables
DEVELOPER_ID_APP_IDENTITY, DEVELOPER_ID_INSTALLER_IDENTITY, APPLE_TEAM_ID.
The apt repository adds secrets APT_GPG_PRIVATE_KEY (armored, no passphrase; both keys during a rotation),
APT_S3_ACCESS_KEY_ID, APT_S3_SECRET_ACCESS_KEY and Variables APT_S3_BUCKET,
APT_REPO_URL (https), plus optional APT_S3_ENDPOINT (R2/GCS) and APT_S3_REGION.
Optional: BEACON_LINUX_SIGNING_KEY (ASCII-armored OpenPGP secret key) and
BEACON_LINUX_SIGNING_KEY_PASSPHRASE, which turn on Linux signing.
Linux signing is trusted only through the fingerprints, one per line, in
cli/beacon/internal/endpoint/selfupdate/release-key.fingerprint. The
self-updater embeds that file and the goreleaser before-hook stamps it into the
released install.sh, so pinning is a change to that file alone. It pins
07BEA34ED6A411F4C066D98322F94195DCDC8F45 (Beacon Linux Release Signing, RSA 4096),
the key that has signed releases since v1.3.57 and the apt repository; that same key's
public half is packaging/linux/apt/beacon-archive-keyring.asc. install.sh and
beacon endpoint update --apply on Linux refuse a package unless a checksums.txt
signed by a pinned key lists it, so every release must be signed (a release without
BEACON_LINUX_SIGNING_KEY fails in the goreleaser job), and the installer refuses the
unsigned releases before v1.3.57. The fingerprint is published in
docs/platforms/linux.mdx#release-signing; change both together.
To rotate, add the new fingerprint in a release still signed by the old key. Then
sign checksums.txt with both keys and ship both in beacon-release-key.gpg (the
GoReleaser signs entry and the finalize step sign with one key today, so extend
both first; gpgv and
validSigFrom accept either pinned key), and keep the old fingerprint pinned until
the fleet has moved. A host that skipped the transition pins only the old key, cannot
verify a new-key-only release, and must reinstall.
Keep one-time Apple-side onboarding steps out of the repo and share them with
the release maintainer directly. Never use pull_request_target or build
untrusted PR code in the signing job.
Use the next semver tag requested by the maintainer, usually the next v0.0.x
tag unless they explicitly decide Beacon is ready for v1.0.0.
Before tagging:
git fetch --tags origin
git status -sb --untracked-files=all
git tag --sort=-v:refname | sed -n '1,8p'
git log --oneline <previous-tag>..HEAD
gh release view <new-tag> --json tagName,url,isDraft,isPrerelease 2>/dev/null || true
git ls-remote --tags origin "refs/tags/<new-tag>"
Run the release gates before publishing:
cd cli/beacon && go test ./...
cd ../beacon-hooks && go test ./...
cd ../../collector-builder/exporter/beaconjsonexporter && go test ./...
cd ../../../pkg/asymptoteobserve && go test ./...
cd ../../packages/asymptote-sdk-js && npm test && npm run check && npm run build && npm run pack:dry-run
cd ../..
sh packaging/macos/test-endpoint-scripts.sh
When building macOS .pkg artifacts, always include the Vector binary by
setting BEACON_VECTOR_BIN (or VECTOR_BIN) to the release Vector executable
before running packaging/macos/build-pkg.sh or
packaging/macos/build-signed-notarized-pkg.sh. The package should install
/opt/beacon/bin/vector so packaged Jamf/Fleet forwarder helpers work without a
separate Vector install.
The Linux .deb, .rpm, and release archives carry Vector too. Run
sh packaging/linux/fetch-vector.sh before GoReleaser: it downloads the static
(musl) build for both arches, checks it against the checksums pinned in packaging/vector/ (never a file from the download host) and
for a program interpreter, and stages it under cli/beacon/release-vector/. The
GoReleaser before-hook fails without it. The packages install it as
/opt/beacon/bin/vector; the archives carry it as beacon-vector, which the
Homebrew formula installs on Linux. The version is pinned in that script at
0.56.0, the same as the macOS package. Vector 0.57 and 0.58 stop expanding the
${VAR} references the generated packs rely on, so bump it only together with
packaging/linux/validate-vector-packs.sh passing against the new version.
Preferred CI Release
CI release automation should:
- Trigger only on pushed tags matching
v*. - Check out the tagged commit with full history (
fetch-depth: 0) so GoReleaser can compute changelogs from the previous tag. - Name that previous tag for GoReleaser (
GORELEASER_PREVIOUS_TAG, the nearestv*tag before this one). Left to itself, GoReleaser takes the nearest tag of any kind, so anext-v*orsdk-js-v*tag between two CLI releases cuts the changelog short; v1.3.47's started atsdk-js-v0.2.0. - Build or restore the collector binaries expected by
.goreleaser.yamlundercollector-builder/dist/beacon-otelcol/<goos>_<goarch>/beacon-otelcol. - Run
goreleaser checkbefore publishing. - Run
goreleaser release --clean --parallelism 1fromcli/beaconbecause the release pre-hook writes target-specificbeacon-hooksbinaries to a shared embedded path. - Provide
GITHUB_TOKENfor the GitHub release andHOMEBREW_TAP_TOKENwith write access toasymptote-labs/homebrew-tap.
The normal deployment flow is:
git fetch --tags origin
git status -sb --untracked-files=all
git tag -a <tag> -m "<tag>"
git push origin <tag>
gh run list --workflow release.yml --limit 5
After the workflow succeeds, verify the GitHub release assets and the Homebrew tap:
gh release view <tag> --json url,tagName,assets --jq '.tagName + " " + .url + " assets=" + (.assets | map(.name) | join(","))'
gh api repos/Asymptote-Labs/homebrew-tap/contents/Formula/beacon.rb --jq '.content' | base64 --decode | sed -n '1,70p'
gh api repos/Asymptote-Labs/homebrew-tap/commits/main --jq '.sha + " " + .commit.message'
Check Homebrew on Linux with a real install, since formula changes only take effect once a release publishes them. It should print a Vector version:
docker run --rm --platform linux/amd64 homebrew/brew sh -c \
'brew install asymptote-labs/tap/beacon && "$(brew --prefix)/bin/beacon-vector" --version'
The release should include the five GoReleaser CLI archives (four .tar.gz plus
beacon_<version>_windows_amd64.zip), checksums.txt, threat-rules.tar.gz, install.sh (the Linux one-line installer from packaging/linux/install.sh),
BeaconEndpointAgent-<version>-arm64.pkg, its .sha256, update-manifest.json,
and BeaconEndpointAgent-<version>-x64.msi with its .sha256. checksums.txt lists
the archives, the Linux packages, the .pkg, the .msi and install.sh, and each of those has a
build-provenance attestation. Once Linux signing is on, the release also carries
checksums.txt.sig and beacon-release-key.{asc,gpg}.
The MSI is unsigned, so pkgutil/stapler/spctl have no Windows counterpart to
run. Its .sha256 is therefore the only integrity check it has, and the release
job proves the package works by installing it on a runner before attaching it —
verification by execution rather than by signature. Both change when Authenticode
signing is added. Verify the package before announcing the release:
tmpdir="$(mktemp -d)"
cd "$tmpdir"
gh release download <tag> --repo Asymptote-Labs/agent-beacon --pattern 'BeaconEndpointAgent-*-arm64.pkg*' --pattern update-manifest.json
shasum -a 256 -c BeaconEndpointAgent-*-arm64.pkg.sha256
gh attestation verify BeaconEndpointAgent-*-arm64.pkg --repo Asymptote-Labs/agent-beacon
pkgutil --check-signature BeaconEndpointAgent-*-arm64.pkg
xcrun stapler validate BeaconEndpointAgent-*-arm64.pkg
spctl --assess --type install -vv BeaconEndpointAgent-*-arm64.pkg
jq . update-manifest.json
For releases that include endpoint self-update changes, validate the manual apply path from the prior installed package on an Apple Silicon Mac:
/opt/beacon/bin/beacon version
sudo /opt/beacon/bin/beacon endpoint update --apply
/opt/beacon/bin/beacon version
/opt/beacon/bin/beacon endpoint status --system
sudo tail -n 20 /var/log/beacon-agent/system.jsonl
If the workflow fails after the tag is pushed, do not create a second tag until the failure is understood. Fix the release workflow or source issue, then rerun the failed workflow for the same tag when possible. Delete and recreate a pushed tag only with maintainer approval.
Local Fallback Release
Do not publish locally from a dirty checkout unless the maintainer explicitly
wants those uncommitted changes in the release archive. If unrelated local
changes are present, create a temporary clean worktree at HEAD and copy the
prebuilt collector binaries into it before running GoReleaser:
rm -rf .tmp/release-<tag>
git worktree add .tmp/release-<tag> HEAD
mkdir -p .tmp/release-<tag>/collector-builder/dist/beacon-otelcol/{darwin_amd64,darwin_arm64,linux_amd64,linux_arm64}
cp collector-builder/dist/beacon-otelcol/darwin_amd64/beacon-otelcol .tmp/release-<tag>/collector-builder/dist/beacon-otelcol/darwin_amd64/beacon-otelcol
cp collector-builder/dist/beacon-otelcol/darwin_arm64/beacon-otelcol .tmp/release-<tag>/collector-builder/dist/beacon-otelcol/darwin_arm64/beacon-otelcol
cp collector-builder/dist/beacon-otelcol/linux_amd64/beacon-otelcol .tmp/release-<tag>/collector-builder/dist/beacon-otelcol/linux_amd64/beacon-otelcol
cp collector-builder/dist/beacon-otelcol/linux_arm64/beacon-otelcol .tmp/release-<tag>/collector-builder/dist/beacon-otelcol/linux_arm64/beacon-otelcol
sh packaging/linux/fetch-vector.sh "$PWD/.tmp/release-<tag>/cli/beacon/release-vector"
Tag and publish from the clean release checkout. Prefer explicitly exported
tokens; use gh auth token only as a local fallback:
git -C .tmp/release-<tag> tag -a <tag> -m "<tag>"
git -C .tmp/release-<tag> push origin <tag>
cd .tmp/release-<tag>/cli/beacon
goreleaser check
GITHUB_TOKEN="${GITHUB_TOKEN:-$(gh auth token)}" HOMEBREW_TAP_TOKEN="${HOMEBREW_TAP_TOKEN:-$(gh auth token)}" goreleaser release --clean --parallelism 1 $([ -n "${BEACON_LINUX_SIGNING_KEY_FPR:-}" ] || echo --skip=sign)
The signs entry signs checksums.txt with the key named by BEACON_LINUX_SIGNING_KEY_FPR (and GNUPGHOME
holding it, as release.yml sets up). The command above adds --skip=sign when the variable is unset, which
publishes an unsigned checksums.txt; once release-key.fingerprint pins a key, installers refuse that release,
so a pinned fallback release must export both. Run without either, the entry fails closed at the sign step (gpg
is asked for a key named BEACON_LINUX_SIGNING_KEY_FPR-unset, never a default key) before anything is published.
GoReleaser OSS has no if/skip on signs, so every snapshot invocation passes --skip=sign itself.
After GoReleaser succeeds, verify both the GitHub release and the Homebrew tap:
gh release view <tag> --json url,tagName,assets --jq '.tagName + " " + .url + " assets=" + (.assets | length | tostring)'
gh api repos/Asymptote-Labs/homebrew-tap/contents/Formula/beacon.rb --jq '.content' | base64 --decode | sed -n '1,70p'
gh api repos/Asymptote-Labs/homebrew-tap/commits/main --jq '.sha + " " + .commit.message'
Clean up the temporary worktree after verification:
git worktree remove --force .tmp/release-<tag>
TypeScript SDK Release
Publish @asymptote/sdk from GitHub Actions instead of a local shell when
possible so npm provenance remains enabled.
Before tagging:
cd packages/asymptote-sdk-js
npm test
npm run check
npm run pack:dry-run
Publish with an annotated SDK tag that matches package.json exactly:
git tag -a sdk-js-v<version> -m "sdk-js-v<version>"
git push origin sdk-js-v<version>
gh run list --workflow npm-publish-sdk.yml --limit 5
The .github/workflows/npm-publish-sdk.yml workflow validates that the pushed
sdk-js-v<version> tag matches packages/asymptote-sdk-js/package.json, reruns
the SDK checks, and publishes to npm with provenance.
Trusted publishing must be configured in npm for this repository/workflow before the first CI publish. If trusted publishing is unavailable and the maintainer explicitly requests a local fallback, disable provenance for that one publish instead of changing the package defaults.
Use these npm trusted publisher values:
- Package:
@asymptote/sdk - Publisher: GitHub Actions
- Organization or owner:
asymptote-labs - Repository:
agent-beacon - Workflow filename:
npm-publish-sdk.yml - Environment:
npm-publish
The workflow runs in the npm-publish GitHub environment, which must allow deployments only from
sdk-js-v* tags. npm accepts a publish only from that environment, so the tag restriction is what
keeps a branch from publishing.
Browser Extension Release
The browser extension versions independently of the CLI. A pushed ext-v* tag
runs .github/workflows/release-extension.yml, which creates its own GitHub
release carrying the unpacked Chromium-family build as a zip plus a .sha256.
The zip keeps its -chrome.zip name: chrome names the Chromium extension
target family, and the same archive loads in Edge, Brave, Opera, Vivaldi and Arc.
ext-v* and the CLI's v* trigger cannot collide: GitHub tag patterns anchor at
the start, so v* does not match ext-v0.1.0.
The extension release is created with --latest=false, so GitHub's "Latest" release
stays the CLI's. The self-updater's update-manifest.json, the Linux install.sh
one-liner, the update notice and the README's download links all resolve
releases/latest; when ext-v0.1.0 took the label they returned 404 until
gh release edit <cli-tag> --latest gave it back.
Bump the version in both browser-extension/package.json and
browser-extension/src/manifest.json before tagging. The workflow requires the
tag and both files to agree and fails otherwise.
cd browser-extension
npm run check && npm run test:unit && npm run build
cd ../
git tag -a ext-v<version> -m "ext-v<version>"
git push origin ext-v<version>
gh run list --workflow release-extension.yml --limit 5
A second job, firefox, signs the Firefox build through AMO as an unlisted
add-on and attaches agent-beacon-browser-extension-<version>-firefox.xpi plus
its .sha256. It runs only when the AMO_JWT_ISSUER and AMO_JWT_SECRET
repository secrets exist, and skips when the release already has that .xpi,
because AMO signs each version once. Without the secrets it is a no-op and the
release still succeeds with the Chrome zip alone.
The sign job signs the same zip as agent-beacon-browser-extension-<version>-chrome.crx
(CRX3) for managed fleets, which force-install it through Chrome policy. It is the
only job that sees the signing key: it runs in the extension-signing environment
(secret CHROME_EXTENSION_SIGNING_KEY, deployments allowed only from ext-v* tags),
checks out only browser-extension/tools, and runs the dependency-free
tools/pack-crx.mjs with plain Node, never npm ci. pack refuses a key whose
extension ID is not CHROME_EXTENSION_ID in tools/targets.mjs, and verify
re-reads the CRX as Chrome does and checks it carries exactly the published zip. A
missing key fails the release. The key fixes the extension ID that every fleet's
policy names, so it is never rotated; a copy is kept in the company password
manager, and losing it means a new extension ID and a policy change for every fleet.
The feed job (one concurrency group across all tags) then picks the highest
published ext-v* release that has a signed CRX and its checksum (pack-crx.mjs newest), not only its own version, because GitHub keeps one waiting job per
concurrency group and cancels the rest. It downloads that CRX from its public
release URL, verifies it, and swaps a new updates.xml in on the fixed
ext-updates release (created on first use, --latest=false --prerelease),
uploading it as updates.xml.new and renaming it so a failed upload leaves the
live feed in place. That file's URL is CHROME_UPDATE_URL, the
manifest's update_url and the URL fleets put in policy, so it must never move
without first shipping a version whose update_url names the new place. The job
refuses to offer a lower version than the feed already does, so re-running an old
tag cannot roll fleets back (a failure to read the current feed fails the job
rather than skipping that check), and reads the feed back through that URL
before finishing. A re-run of a release that already has its zip, CRX and both
checksums keeps them: the rebuilt zip has new file times, so a re-signed CRX
would no longer match the hash the live feed pins. A release left with its CRX
but not the rest fails the run with instructions instead of re-signing.
The zip is unsigned, so its .sha256 is its integrity check, the same posture as
the Windows MSI; Chrome checks the CRX's signature against its ID when it installs
it. The workflow proves the zip works by unzipping the published bytes and
asserting they are a loadable MV3 extension with the pinned update_url. Verify
after the run:
gh release download ext-v<version> --repo Asymptote-Labs/agent-beacon \
--pattern 'agent-beacon-browser-extension-*-chrome.*'
shasum -a 256 -c agent-beacon-browser-extension-<version>-chrome.zip.sha256
shasum -a 256 -c agent-beacon-browser-extension-<version>-chrome.crx.sha256
node browser-extension/tools/pack-crx.mjs verify \
--crx agent-beacon-browser-extension-<version>-chrome.crx \
--zip agent-beacon-browser-extension-<version>-chrome.zip
curl -fsSL https://github.com/Asymptote-Labs/agent-beacon/releases/download/ext-updates/updates.xml
The feed must name <version>, the CRX's release URL and its SHA-256. Chrome Web
Store publication is not wired; unmanaged machines load the zip unpacked through
developer mode.
Implementation Notes
- Prefer deterministic tests that use
t.TempDir(),testenv.SetHome(t, ...)(cli/beacon/internal/testenv; a baret.Setenv("HOME", ...)does not moveos.UserHomeDiron Windows), fake binaries, and free local ports. Gate Unix permission-bit assertions withtestenv.HasPOSIXFileModes()ortestenv.RequirePOSIXFileModes(t), and shell-script fixtures withtestenv.RequirePOSIXExecutableFixtures(t). - Avoid tests that require root, real
launchctlservice changes, Wazuh, a live collector, or external network access. - For macOS-only behavior, gate tests with
runtime.GOOS == "darwin"or assert the non-Darwin contract explicitly. - Keep endpoint event schema fields stable:
vendor,product,schema_version, required event fields, and Wazuh-compatible JSONL output are release contracts. - Preserve optional event fields for agent-native metadata (
session,trace,tool,file,command,mcp,approval,content,model,repository, andbranch) without changing existing required field semantics. - Reading a runtime's own on-disk session store is a
pollcollection path, not a new method: it is a pull that sees committed records after the fact, which is whatpollmeans. fx is the case that exercises it (cli/beacon/internal/fxsession); a future runtime with the same shape usespolltoo rather than adding a value to a release-contract field. The token aggregator relies on that marker: when one session (endpoint, normalized harness, session id) has usage from both a live method andpoll,preferLiveOverPollincli/beacon/internal/tokens/tokens.gokeeps live usage authoritative from the first event of that live channel in the session and drops the backfill's copies from then on, so a poll mapper must keep the runtime's own session id and real record timestamps rather than deduplicating against the live log itself. - Set the provenance markers on every new collection path.
harness.collection_method(hook,otlp,plugin,poll,gateway) records the mechanism;event.fidelity(observed,inferred) records whether the source named the action or Beacon derived it. Both are defined inpkg/asymptoteobserve/provenance.goand are the only sanctioned way to express that difference — do not add per-runtime confidence fields, and do not leave a derived action unmarked. A new plugin-shaped runtime must be added toCollectionMethodForPlatform, whose default ishook. An action synthesized from an adjacent observation, such as an approval built from a pre-tool notification on a runtime with no approval hook, isinferred.gatewayis the one method that is not on the endpoint: a service in the path of model calls (thegateway/module) that sees requests and replies on the wire; it counts as live inpreferLiveOverPoll, and its events carry the gateway host asendpoint. - Keep event identity derivable rather than asserted.
gen_ai.tool.call.idcarries the runtime's own name for one tool invocation, promoted on every capture path from the shared alias list inpkg/asymptoteobserve.ToolCallIDKeys; a new runtime adds its spelling there rather than in a mapper.prompt.idnames the turn an event belongs to (one user prompt and everything done for it, until the next prompt) and is promoted the same way fromasymptoteobserve.PromptIDKeys(hook envelope, OTLP attributes,beacon.prompt.id); session-store mappers set it from the turn they are reading. OTel GenAI has no turn attribute, so the name is Claude Code's own; a spelling joins the list only when the runtime's value is exactly one prompt (Copilot's per-model-call turn ids are excluded). Claude Code hooks carry none, so turn-scoped Claude hooks read the newestpromptIdfrom the transcript tail;UserPromptSubmitmust not, because it runs before the prompt is recorded. A presentpromptobject no longer means "this is a prompt": testprompt.textor the category.event.idis a deterministic UUID derived byEventIDForLinefrom the event about to be written, so both capture paths name one action the same way. Its namespace constant and derivation are a contract: changing either renames every event ID Beacon has written, and a test pins the value. - Keep
gen_ai.usageas the single canonical token-usage representation: normalize all runtime token telemetry (span attributes, metric datapoints, legacyllm.usage.*aliases) into it, mirror OTel GenAI semconv JSON names exactly, and never add parallel or per-harness token fields.gen_ai.usage.cache_creation.ephemeral_1h_input_tokens(optional, Anthropic's own name) is the subset ofcache_creation.input_tokenswritten with a one-hour TTL: a breakdown likereasoninginside output, never added to a total, built withasymptoteobserve.NewCacheCreationUsage(clamps it to the write count) and differenced withGenAIUsageCacheCreationInfo.Minus. It is set by Claude Code session files, Pi-familycacheWrite1hand the browser extension's Claude adapter; Claude Code's OTLP export has no split, and reports price unsplit writes at the five-minute rate.gen_ai.usage.cost_usdcarries runtime-reported cost only and is never written from a price list; list-price estimates are computed only at report time from the embedded catalog (cli/beacon/internal/pricing), are always labeled as estimates, and are never stored in events. cli/beacon/internal/pricingestimates list-price cost for reports: integer-microdollar math over the gen_ai.usage counts (disjoint input/output/cache read/cache write, a one-hour write subset, reasoning inside output), long-context bands only for a single request, and a strict model-name ladder (exact, canonical viaNormalizeModelName, dotted version, Bedrock route prefix, then stripping a[1m]marker, snapshot date or effort suffix) that leaves a model unpriced rather than guess, including when two entries tie with different prices. Itscatalog.jsonis embedded, offline and report-time only (hooks never import it); it is generated from LiteLLM's MIT-licensedmodel_prices_and_context_window.jsonand records the upstream URL, commit and fetch/generation dates. Regenerate withcd cli/beacon && go run ./internal/pricing/internal/gen(resolves LiteLLM's main withgit ls-remoteand fetches that commit;-src/-commitfor a local copy) and review the one-model-per-line diff; the generator never runs in builds or tests. Operators price what the catalog cannot (internal models, new releases, gateway aliases, negotiated rates) in a local overrides file,<BaseDir>/pricing/overrides.json(pricing.DefaultOverridesPath, user or system mode;--pricing-fileonbeacon token-usageandbeacon pricingnames another), schemabeacon.pricing.overrides/v1, documented indocs/cli/pricing.mdx. It is offline and Beacon never writes it: the CLI reads it per run, and the dashboard re-reads it per/api/tokensrequest, read-only, falling back to the catalog withpricing.overrides.errorwhen it is invalid (the CLI fails instead). Rates are USD per MTok converted exactly to microdollars; zero, negative, quoted, sub-microdollar, absurd, unknown and duplicate keys are refused with the key named.Pricer.Lookupruns the same ladder over the file's names first and a row replaces the catalog row whole (omitted cache rates are unpublished, priced by the usual fallbacks); aliases map a reported name to an exact row or catalog key. Reports recordsource(override/catalog),alias, and the file's path and SHA-256.beacon pricing show|list|info|validate(cli/beacon/cmd/pricing.go) inspects resolution, the catalog, its provenance and the file.- When adding a new signal, include stable identifiers/counts/hashes alongside any retained raw content, and route raw fields through redaction, sanitization, truncation, and event-size controls.
- Keep the dashboard read-only. It should inspect local status and JSONL events but must not mutate endpoint configuration or telemetry.
- A few no-op extension points let a separately distributed build compile in files of its own:
claudeExtraHookGroupsandclaudeSettingsChanged(cli/beacon/internal/endpoint/hooks/claude.go),cursorExtraHooksandcursorHooksChanged(cursor.go; an event the map names with no entries is still stripped of Beacon's, which is how a build stops installing a hook there),codexExtraHookGroupsandcodexHooksChanged(codex.go),declaredPlatformin the hook adapter (cli/beacon-hooks/cmd/helpers.go: the--platforma hook was invoked with, kept when a Cursor payload on a Claude Code hook switchesplatformFlag; the public adapter also reads it to skip those duplicate runs),version.Edition(both modules; reported bybeacon version,endpoint status --jsonand the inventory heartbeat only when it is notcommunity), andupdatecheck.PublicReleases(false turns off the startup notice,beacon version checkand the self-updater). In this repository they stay unset, and with them unset Beacon must behave exactly as before:TestInstallClaudeSettingsUnchangedWithoutExtensions,TestCursorHooksGoldenandTestCodexHooksGoldencompare what the installer writes (and an uninstall leaves) to golden files, with the points cleared bywithoutHookExtensionsso they hold in a build that fills them. Keep them neutral, with no product logic behind them here, and CI refuses any file built only with anenterprisetag. The one exception isbeacon endpoint enforcement enable(cli/beacon/cmd/endpoint_enforcement.go), the public installer for the enterprise edition: on an Apple Silicon Mac connected in system mode, with no user-mode Beacon running for the console user, it asks<dashboard>/api/cli/enforcement/downloadfor the enterprise package (internal/endpoint/edition), installs it withselfupdate.Applier.InstallPackage(the self-updater's steps after discovery, with no version gate; the package must match the checksum, be signed by the Apple team pinned inedition.AppleTeamID, pass Gatekeeper and report the version andenterpriseedition once installed, or it is rolled back), then runs the installed binary's ownenable. A build that carries enforcement setsactivateEnforcement, whichenableruns instead, and adds its other subcommands toendpointEnforcementCmd. It contains no enforcement logic, never runs from hooks or in the background, and withactivateEnforcementunset nothing else changes. - The gateway module (
gateway/, its own Go module;gateway/README.md) has the same kind of no-op extension points, ingateway/cmd/beacon-gateway/extend.go:analyzerFactories(by name, each built from its ownanalyzers.<name>node and run after the events analyzer),policyFactory(nil keepspipeline.AllowAll),storeFactories(bystore.type;memoryis built in)observerFactories(by name,observers.<name>) andsinkFactories(by an output'stype;jsonlis built in, and an entry with onlyjsonl: <path>is one). The open config parser names none of an extension's keys. With them empty every call is allowed, and since nothing can change a verdict the pipeline answers each call at admission and analyzes it afterwards (pipeline.Inlineor a policy turns that off). The HTTP callout adapters read bodies into pooled buffers (gateway.ReadBody) that the pipeline hands back throughCall.Releaseonce it has read the call, and the LiteLLM adapter builds a request's body over its payload: no extension may keep apipeline.Turn, itsCall, or anything sliced fromCall.BodypastAnalyze,ObserveorDecide(TestReleasedBodiesAreNotReadpoisons every released buffer and checks the records). Gateway events carryharness.collection_method=gateway; the events analyzer builds them once and leaves them onpipeline.Turn.Eventsfor analyzers after it; ids come fromasymptoteobserve.EventIDwhen an event is written or cited, never on the call path, and so do the fields no rule can address (content markers, gen_ai message copies, tool-call arguments:pipeline.Event.Complete, applied byWritten(), which an analyzer that needs them calls). A tool call is recorded as the action it asks for (command.executed,file.read,mcp.tool_invoked,tool.invoked) before the harness acts; a read's or MCP tool's result repeats the action but never carries the call's target (nofile.path, nomcpblock ortool.name, which are whatdedupeTargetreads; the call's arguments go ongen_ai.tool.call.argumentsinstead), so call and result never share an event id whatever replica saw the call, and a target rule fires once. Block rendering in every adapter is exercised by the test-only decider ingateway/internal/gatewaytest. Validate withcd gateway && go vet ./... && go test ./... && go test -race ./pipeline/... ./events/... ./litellm/... ./envoy/... ./portkey/... ./llm/.... - The local trace history (
~/.beacon/endpoint/history.db,cli/beacon/internal/endpoint/dashboard/history_*.go) is opt-in: onlybeacon endpoint traces reindex, a yes to the first-run prompt, or (later)beacon mcp setupcreates it, and nothing non-interactive is ever prompted. Once it exists,list,searchandshowmust return exactly what the JSONL scan returns for the same log (TestHistoryAnswersExactlyLikeTheJSONLScan), so it stores every event and projects it with the same code. A change to the trace projection bumpshistoryDerivationVersion, which rebuilds derived data from the stored lines. The stored lines keep only the raw keys inhistoryRawKeys, and a test fails if the dashboard reads one that is missing. The line dictionary (historyLineDictionary) must never change without a new codec. - The Asymptote device key has exactly one home,
<BaseDir>/asymptote/vector-secrets.json, read by Vector'ssecretfile backend. Never copy it intoconfig.json,vector.toml, a service unit, an environment variable, a log line, or a--jsonresult. Besides Vector, only the root CLI reads it, into memory, to authenticate the one requestbeacon endpoint enforcement enablemakes to the platform (and that a build carrying enforcement makes to turn it on or update it);HasSecretDestinationsis unchanged because the key is not inconfig.json.internal/authis flow-agnostic (PKCE, loopback callback server with an injected exchange function, browser opener,PostJSON); new browser flows reuse it rather than adding a second callback server.connectmust fail before opening a browser when Vector or a service manager is missing, or when Vector rejects the rendered config, so no key is minted or rotated that cannot be used; enrollment rotates a connected device's key in place, so every local check runs ahead of it; the steps that can only fail after the exchange (storing the key, writing the config and unit, starting the service) are covered by theasymptote/connect-pendingmarker, written as soon as the key arrives and removed only when connect finishes, so status reports an incomplete connect instead of the previous connection. A failed first connect stops and removes any partial forwarder before returning, which keeps a later local-only onboarding choice local. - Keep the release readiness guidance in
README.mdup to date when install, packaging, collector, or dashboard behavior changes.
CI Expectations
.github/workflows/ci.yml runs these jobs on every pull request and on pushes to main:
go-test(macOS):bun run check && bun testinplugins/sharedand all seven plugin directories, thenmake build-hooks-current, thengo test ./...incli/beacon,go test -race ./internal/endpoint/...,go test ./...incli/beacon-hooks,collector-builder/exporter/beaconjsonexporter, andpkg/asymptoteobserve(includes threat-rules pack conformance), then CLI help smoke checks that also assert removed commands stay unexposed.linux-test(ubuntu) andwindows-test(windows-2025) rerun the Go suites per platform. The Windows job tests a measured package list rather than./...; the excluded packages are tracked in #318, and the scope must not be widened back to./....typescript-sdk(Node 20, 22, 24):npm test,npm run check,npm run build,npm run pack:dry-run,npm run pack:smokeinpackages/asymptote-sdk-js.browser-extension(Node 22, matrix overchromiumandmsedge):npm run check,npm run test:unit,npm run build, a check that the build is a loadable MV3 extension,npm run lint:firefox(the Firefox build plusaddons-linter --warnings-as-errors), and the Playwright replay e2e running the real extension headless in that leg's browser (BROWSER_CHANNEL) against a local HTTPS replay server; the HTML report and traces upload on failure. Brave, Opera, Vivaldi and Arc have no Playwright channel;BROWSER_EXECUTABLEruns the same e2e against their binaries for the manual checklist indocs/runtimes/browser-extension-chromium.mdx.browser-extension-policy(ubuntu, Google Chrome):e2e/policy-install.spec.tswithPOLICY_E2E=1. It signsdist/with a throwaway key, serves the CRX andupdates.xmlfrom a local feed, writes Chrome machine policy under/etc/opt/chrome/policies/managedwith sudo (a*blocklist, a force-install of the test ID withoverride_update_url, and managed values), then checks the install, the locked popup, a replayed chat arriving with metadata only at the locked endpoint, and an update to the next version. Linux is the only platform where Chrome honors an off-store force-install without a managed device, which is why it runs there.lens-e2e(ubuntu): runs the real dashboard handler with hostile fixture lenses and the fullrules/corpus installed (cli/beacon/internal/endpoint/dashboard/e2eserver,testdata/lens-e2e) and drives the session page in headless Chromium. Every escape from the lens sandbox must be refused, and a lens that throws, stalls or navigates must give way to the full session.- The three browser jobs run on
ubuntu-26.04, notubuntu-latest, and install nothing with apt: noplaywright install-depsor--with-deps. They use the runner image's Google Chrome and Microsoft Edge and the system libraries it carries for them, and download only Playwright's Chromium from its CDN, so an Ubuntu mirror outage does not fail them. A new runner image has to keep shipping Chrome and Edge; the Playwright version needs Ubuntu 26.04 support (1.61 or later). beacon-sandbox(ubuntu):go build,go vet, andgo testfor the verification harness. Hermetic — no Modal account, no API key, no paid resources.terraform(ubuntu):terraform fmt -check,validate, andterraform test(mocked providers) for every module underterraform/, andvalidatefor each example.cross-build(ubuntu): builds all five release targets and asserts the Linux binaries are statically linked (noPT_INTERP).package-smoke(macOS):packaging/macos/test-endpoint-scripts.sh, abuild-pkg.shpayload check, andpackaging/macos/smoke-endpoint.sh.linux-systemd-smokeandlinux-package-smoke(ubuntu): the real systemd install path, and installing the built.deband.rpmin a systemd container. The containers come prebuilt from GHCR (ghcr.io/asymptote-labs/beacon-smoke-*, public), published bysmoke-images.ymlfrompackaging/linux/smoke/*.Dockerfileon a change tomainand weekly from a fresh base, and tagged by a digest of the Dockerfile;packaging/linux/smoke/image.shpulls the tag and builds locally when it is not published yet. So these jobs never run apt or dnf against a distribution mirror. A publish moves the tag only after the image boots systemd, and also pushes<digest>-YYYYMMDDto roll back to (image.shshows the command). Onmainonly, the workflow prunes by recipe (packaging/linux/smoke/prune.sh: the newest four versions of the checked-out Dockerfile's digest, and other digests or untagged versions after 30 days) and tracks a failed publish in one open issue titledSmoke images: publish failing.windows-package-smoke(windows-2025):packaging/windows/test-endpoint-scripts.ps1, then fetching the pinned Vector, building the MSI and installing it.
The Go jobs build the embedded hooks binary first (make build-hooks-current); cli/beacon tests
fail against the placeholder because InstallFactory requires a real binary.