The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Docs accuracy pass for managed ingest, onboarding and harness flags
shukieshah1ae47adb1879
diff --git a/CLAUDE.md b/CLAUDE.mdindex 64f626c2..c5c99b7b 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -20,7 +20,7 @@ Do not recreate or depend on removed `asymptote` mirror trees. Keep new work foc- 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.- Asymptote Managed forwarding (`cli/beacon/internal/endpoint/asymptote`, `beacon endpoint asymptote`) is the one destination that sends telemetry to an Asymptote-run service, and it is an explicit, opt-in, revocable Vector destination shaped like every other pack: Beacon stays the local JSONL producer, Vector does the network, and the per-device key lives in a `0600` secrets file read through Vector's secret backend, never in `config.json`, `vector.toml`, or the process environment. Nothing is forwarded until a member of the organization approves the specific device in the browser; only lines written after that are shipped (`read_from = "end"`); revocation from the dashboard takes effect at the ingest service within a minute. The wire contract (gzip NDJSON to `/v1/ingest/{runtime,inventory}`, bearer `bcn_device_*` key, `/v1/ingest/health` credential check) is owned by the `beacon-ingest` service in beacon-mdr; change both sides together. Do not add a second network channel, and do not let the ingest URL be anything but `https://`.-- Two bounded network channels exist, both explicit. The first: `beacon endpoint install` asks for an email and work/personal intent once per machine and POSTs that plus install context (OS, arch, version, install method, detected runtime names, a random install ID) to an Asymptote-run signup endpoint. The same first-run prompt ends with a telemetry destination question (arrow-key picker, local first so Enter forwards nothing): keep it local, forward to the user's own infrastructure (prints the log-forwarding docs URL, nothing else changes), or forward to Asymptote Managed. `BEACON_MANAGED_INGEST=0` hides the Asymptote row; `install --connect` skips the question and connects. Local and own-infrastructure answers are recorded in the profile and never asked again; the Asymptote answer runs `connect` after the install, is recorded only once that connect succeeds so a failed install or connect is asked again rather than remembered as done, and is the only way onboarding ever forwards telemetry. The answer is never sent. The second channel is that forwarder, described below. This is intentional product behavior for open-source attribution, not an oversight — do not remove it. It is strictly bounded: interactive TTY only, once per machine, never during hook execution, never on `--system`/root/CI/piped-stdin/`--dry-run` installs, and always skippable with `--no-onboarding` or `BEACON_ONBOARDING=0`. A failed submission never fails an install. No prompt text, telemetry event, file content, or command ever leaves the machine through it. Implementation lives in `cli/beacon/internal/onboarding` and `cli/beacon/cmd/endpoint_onboarding.go`; the README documents the payload field-by-field, so changing the fields means changing that table too.+- Two bounded network channels exist, both explicit. The first: `beacon endpoint install` asks for an email and work/personal intent once per machine and POSTs that plus install context (OS, arch, version, install method, detected runtime names, a random install ID) to an Asymptote-run signup endpoint. The same first-run prompt ends with a telemetry destination question (arrow-key picker, local first so Enter forwards nothing): keep it local, forward to the user's own infrastructure (prints the log-forwarding docs URL, nothing else changes), or forward to Asymptote Managed. `BEACON_MANAGED_INGEST=0` hides the Asymptote row; `install --connect` skips the question and connects. Local and own-infrastructure answers are recorded in the profile and never asked again; the Asymptote answer runs `connect` after the install, is recorded only once that connect succeeds so a failed install or connect is asked again rather than remembered as done, and is the only way onboarding ever forwards telemetry. The answer is never sent. The second channel is that forwarder, described below. This is intentional product behavior for open-source attribution, not an oversight — do not remove it. It is strictly bounded: interactive TTY only, once per machine, never during hook execution, never on `--system`/root/CI/piped-stdin/`--dry-run` installs, and always skippable with `BEACON_ONBOARDING=0`. A failed submission never fails an install. No prompt text, telemetry event, file content, or command ever leaves the machine through it. Implementation lives in `cli/beacon/internal/onboarding` and `cli/beacon/cmd/endpoint_onboarding.go`; the README documents the payload field-by-field, so changing the fields means changing that table too.- 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 direct destination support scoped to local JSONL/Wazuh unless explicitly requested. Elastic support is a file-tailing pack over local JSONL; Beacon itself must not store Elastic credentials or require a hosted Elastic dependency.diff --git a/cli/beacon/README.md b/cli/beacon/README.mdindex 3762bdbb..e8857ee4 100644--- a/cli/beacon/README.md+++ b/cli/beacon/README.md@@ -13,6 +13,8 @@ make build```bash./beacon endpoint install./beacon endpoint status --json+./beacon endpoint connect+./beacon endpoint disconnect./beacon endpoint discover --json./beacon endpoint repair./beacon endpoint dashboard@@ -494,6 +496,37 @@ and a `BeaconRuntime_CL` custom Log Analytics table. Store Azure workspace,DCR, endpoint, and credential details in Azure or customer-managed deploymenttooling, not in Beacon endpoint configuration.+## Asymptote Managed++```bash+./beacon endpoint connect+./beacon endpoint status --json | jq .managed_ingest+./beacon endpoint disconnect+```++Asymptote Managed is the one destination that forwards telemetry to an+Asymptote-run service, and it is opt-in. `beacon endpoint connect` opens the+Asymptote dashboard so a member of your organization can approve this device,+stores the per-device key in a `0600` secrets file, and runs Vector as the+`com.beacon.endpoint.asymptote-forwarder` (launchd) or+`beacon-asymptote-forwarder.service` (systemd) service. Beacon stays the local+JSONL producer and Vector does the network. Only lines written after approval+are shipped, and revoking the device from the dashboard stops ingestion within+about a minute. Vector 0.56 or newer is required: `/opt/beacon/bin/vector` from+the signed package, `vector` from Homebrew, or the Linux package from+vector.dev.++The same pack is available for running Vector by hand:++```bash+./beacon endpoint asymptote print-config+./beacon endpoint asymptote install-pack --output ./beacon-asymptote-pack+./beacon endpoint asymptote validate+```++See https://docs.asymptotelabs.ai/log-forwarding/asymptote for the wire+contract, what leaves the machine, and revocation.+## Optional Integrations```bashdiff --git a/docs/cli/endpoint-config.mdx b/docs/cli/endpoint-config.mdxindex d3217e66..97eb2baf 100644--- a/docs/cli/endpoint-config.mdx+++ b/docs/cli/endpoint-config.mdx@@ -80,6 +80,19 @@ Validate system endpoint config:sudo beacon endpoint config validate --system```+## Managed ingest block++When the endpoint is connected to Asymptote managed ingest, `config.json` carries a non-secret `managed_ingest` block:++| Field | Meaning |+|-------|---------|+| `enabled` | `true` while the endpoint is connected |+| `ingest_url` | The `https://` ingest URL returned by enrollment |+| `device_id` | This device's id in the Asymptote dashboard |+| `organization_id` | The organization that approved the device |++[`beacon endpoint connect`](/cli/endpoint-connect) writes the block and `beacon endpoint disconnect` clears it. It never holds the device key, which lives only in `asymptote/vector-secrets.json`, and it survives re-running `beacon endpoint install`.+## Related<Columns cols={2}>diff --git a/docs/cli/endpoint-connect.mdx b/docs/cli/endpoint-connect.mdxindex 8c8becae..fc3e4263 100644--- a/docs/cli/endpoint-connect.mdx+++ b/docs/cli/endpoint-connect.mdx@@ -28,19 +28,22 @@ beacon endpoint disconnect [flags]4. Renders `asymptote/vector.toml` from the [Asymptote pack](/cli/asymptote) template with the ingest URL returned by enrollment, runs `vector validate`, installs a service unit and starts it.5. Records the non-secret enrollment (device id, organization, ingest URL) in `asymptote/enrollment.json` and `config.json`'s `managed_ingest` block.-Re-running `connect` on a connected machine reuses its install id, so the server rotates the existing device's key in place instead of creating a second device.+A connect that fails at `vector validate` or at loading the service saves no enrollment record, so the endpoint is not connected: `beacon endpoint status` says so, the next interactive install offers the destination question again, and `beacon endpoint disconnect` cleans up what was written. After `disconnect --keep-credentials`, status reports not connected and names the kept device id.++Re-running `connect` on a connected machine reuses its install id, so the server rotates the existing device's key in place instead of creating a second device. Under launchd the new forwarder is loaded only after the old one has exited (Vector drains in-flight requests first), and if the new instance has not started within the wait, `connect` fails and points at `launchctl print` for the job (v1.3.2).## Files and services| Item | User mode | System mode (macOS) | System mode (Linux) ||------|-----------|---------------------|---------------------|| Enrollment record | `~/.beacon/endpoint/asymptote/enrollment.json` (0600) | `/Library/Application Support/Beacon/Endpoint/asymptote/enrollment.json` | `/etc/beacon/endpoint/asymptote/enrollment.json` |+| Install id | `~/.beacon/endpoint/asymptote/install-id` (0600) | `…/Endpoint/asymptote/install-id` | `/etc/beacon/endpoint/asymptote/install-id` || Device key | `~/.beacon/endpoint/asymptote/vector-secrets.json` (0600) | `…/Endpoint/asymptote/vector-secrets.json` | `/etc/beacon/endpoint/asymptote/vector-secrets.json` || Vector config | `~/.beacon/endpoint/asymptote/vector.toml` (0644, no secret) | `…/Endpoint/asymptote/vector.toml` | `/etc/beacon/endpoint/asymptote/vector.toml` || Buffer and checkpoints | `~/.beacon/endpoint/asymptote/vector-data/` | `…/Endpoint/asymptote/vector-data/` | `/etc/beacon/endpoint/asymptote/vector-data/` || Service | `~/Library/LaunchAgents/com.beacon.endpoint.asymptote-forwarder.plist` | `/Library/LaunchDaemons/com.beacon.endpoint.asymptote-forwarder.plist` | `/etc/systemd/system/beacon-asymptote-forwarder.service` (user mode: `~/.config/systemd/user/`) |-The directory is `0700`. The device key appears only in the secrets file, which Vector reads through its `file` secret backend; it is in neither `vector.toml`, `config.json`, nor the forwarder's environment.+The directory is `0700`. The device key appears only in the secrets file, which Vector reads through its `file` secret backend; it is in neither `vector.toml`, `config.json`, nor the forwarder's environment. `install-id` pins this machine's install id before enrollment starts, so a connect retried after a failure rotates the same device's key instead of registering a second device.## Flags@@ -54,7 +57,7 @@ The directory is `0700`. The device key appears only in the secrets file, which| `--log-path <path>` | Runtime JSONL log path || `--json` | Print the result as JSON (the device key is never included) |-`disconnect` accepts the same path flags plus `--keep-credentials`, which keeps the enrollment record and device key so a later `connect` can reuse this device without a new approval.+`disconnect` accepts the same path flags and `--json` (which prints `disconnected`, `kept_credentials`, and `device_id`), plus `--keep-credentials`, which keeps the enrollment record and device key so a later `connect` can reuse this device without a new approval.## Examples@@ -87,7 +90,7 @@ Asymptote managed ingest: connected to Asymptote Test as device 807c6a11-…; fo## Revocation and disconnect-Revoke a device, or every device a person approved, from the dashboard's **Beacon Endpoints** page. The ingest service rejects the key within about a minute. `disconnect` is the local half: it stops and removes the forwarder and its config and, unless `--keep-credentials` is given, the enrollment record and device key. `beacon endpoint uninstall` does the same as part of removing the endpoint. Neither revokes the device server-side; the CLI tells you where to do that.+Revoke a device, or every device a person approved, from the dashboard's **Beacon Endpoints** page. The ingest service rejects the key within about a minute. `disconnect` is the local half: it stops and removes the forwarder and its config and, unless `--keep-credentials` is given, the enrollment record and device key. `beacon endpoint uninstall` removes the forwarder and the `asymptote/` directory as part of removing the endpoint, except that `--keep-config` keeps the enrollment record and device key. Neither revokes the device server-side; the CLI tells you where to do that.## Offline behaviordiff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdxindex 4703c3f2..7ecc67b5 100644--- a/docs/cli/endpoint-install.mdx+++ b/docs/cli/endpoint-install.mdx@@ -22,11 +22,13 @@ By default, Beacon configures Claude Code and Codex CLI telemetry for local or c| `--user` | Use per-user endpoint paths. Enabled by default || `--system` | Use system endpoint paths and launch daemon. Requires root || `--log-path <path>` | Runtime JSONL log path |-| `--harness <list>` | Comma-separated harnesses to configure. Defaults to `claude,codex`; include `gemini` for Gemini CLI, `vscode` for VS Code Copilot telemetry, `devin-cli` for Devin CLI hooks, or `devin-desktop` for Devin Desktop hooks. Claude Code, Grok Build, Hermes Agent, Cursor, Factory, OpenCode, Cline, Qwen Code, and optional VS Code hook telemetry are managed with `beacon endpoint hooks`. GitHub Copilot CLI and Factory Droid OTLP endpoints are managed through their launch environments |+| `--harness <list>` | Comma-separated harnesses to configure. Defaults to `claude,codex`; include `gemini` for Gemini CLI or `vscode` for VS Code Copilot OTLP telemetry. Hook harnesses can be listed alongside them: `claude-hooks` (Claude Code hooks), `cursor`, `factory`, `opencode`, `cline`, `pi`, `omp`, `grok`, `qwen`, `hermes`, `antigravity`, `devin-cli`, and `devin-desktop`, for example `beacon endpoint install --harness claude,codex,cursor`. `beacon endpoint hooks install` adds the same hooks to an existing install later, and is the only way to add VS Code hook telemetry. GitHub Copilot CLI and Factory Droid OTLP endpoints are managed through their launch environments || `--otlp-grpc-port <port>` | Local OTLP gRPC port. Defaults to `4317` || `--otlp-http-port <port>` | Local OTLP HTTP port. Defaults to `4318` || `--collector <path>` | Path to a `beacon-otelcol` binary || `--no-start` | Write files without starting the collector service |+| `--service <kind>` | Service manager to use: `auto` (default), `launchd`, `systemd`, or `none` for a supervised collector process |+| `--dry-run` | Print planned actions without changing endpoint files or services || `--include-runtime-metrics` | Include generic process, runtime, and harness operational OTLP metrics in Beacon JSONL. By default, low-signal metrics such as process CPU, memory, Node.js event loop, V8 heap, GitHub Copilot CLI, and OpenClaw operational metrics are filtered out || `--include-codex-spans` | Include every high-volume Codex OTLP span for troubleshooting. By default, Beacon keeps semantic logs and only the usage-bearing completed turn span || `--splunk-hec-endpoint <url>` | Splunk HEC endpoint URL |@@ -169,7 +171,7 @@ Install Qwen Code hooks at the user level:beacon endpoint hooks install --harness qwen```-Qwen Code hooks merge into `~/.qwen/settings.json`. Qwen Code has no OpenTelemetry export to configure, so `beacon endpoint install --harness qwen` fails with a message pointing at `beacon endpoint hooks install` rather than appearing to succeed.+Qwen Code hooks merge into `~/.qwen/settings.json`. Qwen Code has no OpenTelemetry export to configure, so `qwen` is a hook harness on this command too: `beacon endpoint install --harness qwen` installs the same hooks and writes `~/.qwen/settings.json`.Project-level Grok Build hooks write `./.grok/hooks/beacon-endpoint.json` and require `/hooks-trust` in Grok before they execute:@@ -181,6 +183,10 @@ beacon endpoint hooks install --harness grok --level projectSystem-mode install (`--system`) is supported on macOS and on Linux distributions that use systemd. Omit `--system` for the default non-root local install. GitHub Copilot CLI and Factory Droid OTLP use launch-environment settings rather than Beacon-managed shell-profile edits.</Note>+## Known limitations++A user-mode collector cannot run beside a system-mode one on the same machine. The collector health-check port (`127.0.0.1:13133`) is fixed, so the second collector cannot bind it; the install fails with `Collector ports are not listening` and rolls back the endpoint files it wrote. Either write the user-mode files without starting the service (`beacon endpoint install --user --no-start`) or uninstall the system endpoint first (`sudo beacon endpoint uninstall --system`). Tracked as [GitHub issue #447](https://github.com/Asymptote-Labs/agent-beacon/issues/447).+## Related<Columns cols={2}>diff --git a/docs/cli/endpoint-onboarding.mdx b/docs/cli/endpoint-onboarding.mdxindex a45a43f8..ad8b384e 100644--- a/docs/cli/endpoint-onboarding.mdx+++ b/docs/cli/endpoint-onboarding.mdx@@ -13,7 +13,9 @@ beacon endpoint onboarding [flags]```The record lives in `~/.beacon/profile.json`. It survives uninstall, so reinstalling-Beacon does not ask again.+Beacon never asks the email and usage questions again. The destination question is+asked again on the next interactive install until a destination is recorded; an+Asymptote answer is recorded only once the connect succeeds.## First-run onboarding@@ -37,7 +39,9 @@ not an ongoing channel.The prompt never appears non-interactively. Package postinstall scripts, MDMdeployments, `--system` installs, CI, `--dry-run`, and any piped or redirected stdin-skip it silently.+skip it silently. The destination question is also skipped on an endpoint already+connected to Asymptote. A machine onboarded before the question existed is asked it+once, on its next interactive install.## Flags@@ -82,6 +86,15 @@ connected machine):beacon endpoint onboarding```+The answer is stored as `onboarding.destination` in `~/.beacon/profile.json` and takes+one of three values; `--json` exposes it as `destination`:++| Value | Printed as |+|-------|------------|+| `local` | local only (nothing forwarded) |+| `own_infra` | own infrastructure (forwarding pack) |+| `asymptote` | Asymptote Managed |+Clear it so the next install asks again:```bash title="Reset the onboarding record"diff --git a/docs/cli/endpoint-paths.mdx b/docs/cli/endpoint-paths.mdxindex db0aa413..c3f30bc6 100644--- a/docs/cli/endpoint-paths.mdx+++ b/docs/cli/endpoint-paths.mdx@@ -15,10 +15,11 @@ Beacon manages different paths depending on whether you install in user mode or| Rotated runtime archives | `~/.beacon/endpoint/logs/runtime.jsonl.1` through `.5` | `/var/log/beacon-agent/runtime.jsonl.1` through `.5` | `/var/log/beacon-agent/runtime.jsonl.1` through `.5` | `%ProgramData%\Beacon\Endpoint\logs\runtime.jsonl.1` through `.5` || Threat rule store | `~/.beacon/endpoint/rules` | `/Library/Application Support/Beacon/Endpoint/rules` | `/etc/beacon/endpoint/rules` | `%ProgramData%\Beacon\Endpoint\rules` || Collector config | `~/.beacon/endpoint/otelcol.yaml` | `/Library/Application Support/Beacon/Endpoint/otelcol.yaml` | `/etc/beacon/endpoint/otelcol.yaml` | `%ProgramData%\Beacon\Endpoint\otelcol.yaml` |-| Managed-ingest state (`beacon endpoint connect`) | `~/.beacon/endpoint/asymptote/` (`enrollment.json`, `vector-secrets.json`, `vector.toml`, `vector-data/`) | `/Library/Application Support/Beacon/Endpoint/asymptote/` | `/etc/beacon/endpoint/asymptote/` | Not yet supported |+| Managed-ingest state (`beacon endpoint connect`) | `~/.beacon/endpoint/asymptote/` (`enrollment.json`, `install-id`, `vector-secrets.json`, `vector.toml`, `vector-data/`) | `/Library/Application Support/Beacon/Endpoint/asymptote/` | `/etc/beacon/endpoint/asymptote/` | Not yet supported || Installed binaries | None | `/opt/beacon/bin` | `/opt/beacon/bin` | `%ProgramFiles%\Beacon\bin` || OTLP gRPC | `127.0.0.1:4317` | `127.0.0.1:4317` | `127.0.0.1:4317` | `127.0.0.1:4317` || OTLP HTTP | `127.0.0.1:4318` | `127.0.0.1:4318` | `127.0.0.1:4318` | `127.0.0.1:4318` |+| Collector health check | `127.0.0.1:13133` | `127.0.0.1:13133` | `127.0.0.1:13133` | `127.0.0.1:13133` |On Windows the system log directory sits under the base directory rather than in a separate location, because there is no `/var/log` equivalent. `%ProgramData%` and `%ProgramFiles%` are read from the environment rather than hardcoded, so a relocated or localized install is found rather than missed.diff --git a/docs/cli/endpoint-repair.mdx b/docs/cli/endpoint-repair.mdxindex 66726ec4..bbfca88f 100644--- a/docs/cli/endpoint-repair.mdx+++ b/docs/cli/endpoint-repair.mdx@@ -22,11 +22,13 @@ During repair, Beacon removes the existing managed service before reinstalling i| `--user` | Use per-user endpoint paths. Enabled by default || `--system` | Use system endpoint paths and launch daemon || `--log-path <path>` | Runtime JSONL log path |-| `--harness <list>` | Comma-separated harnesses to configure. Defaults to `claude,codex`; include `gemini` to opt in Gemini CLI telemetry, `vscode` for VS Code Copilot telemetry, `devin-cli` for Devin CLI hooks, or `devin-desktop` for Devin Desktop hooks. Claude Code, Grok Build, Cursor, Factory, OpenCode, Cline, and Qwen Code hook telemetry are managed with `beacon endpoint hooks`. GitHub Copilot CLI and Factory Droid OTLP endpoints are managed through their launch environments |+| `--harness <list>` | Comma-separated harnesses to configure. Defaults to `claude,codex`; include `gemini` for Gemini CLI or `vscode` for VS Code Copilot OTLP telemetry. Hook harnesses can be listed alongside them: `claude-hooks` (Claude Code hooks), `cursor`, `factory`, `opencode`, `cline`, `pi`, `omp`, `grok`, `qwen`, `hermes`, `antigravity`, `devin-cli`, and `devin-desktop`, for example `beacon endpoint repair --harness claude,codex,cursor`. `beacon endpoint hooks install` adds the same hooks to an existing install later, and is the only way to add VS Code hook telemetry. GitHub Copilot CLI and Factory Droid OTLP endpoints are managed through their launch environments || `--otlp-grpc-port <port>` | Local OTLP gRPC port. Defaults to `4317` || `--otlp-http-port <port>` | Local OTLP HTTP port. Defaults to `4318` || `--collector <path>` | Path to a `beacon-otelcol` binary || `--no-start` | Write files without starting the collector service |+| `--service <kind>` | Service manager to use: `auto` (default), `launchd`, `systemd`, or `none` for a supervised collector process |+| `--dry-run` | Print planned actions without changing endpoint files or services || `--include-runtime-metrics` | Include generic process, runtime, and harness operational OTLP metrics in Beacon JSONL. By default, low-signal metrics such as process CPU, memory, Node.js event loop, V8 heap, GitHub Copilot CLI, and OpenClaw operational metrics are filtered out || `--include-codex-spans` | Include every high-volume Codex OTLP span for troubleshooting. By default, Beacon keeps semantic logs and only the usage-bearing completed turn span || `--splunk-hec-endpoint <url>` | Splunk HEC endpoint URL |diff --git a/docs/cli/endpoint-status.mdx b/docs/cli/endpoint-status.mdxindex 63bda880..d1d79a36 100644--- a/docs/cli/endpoint-status.mdx+++ b/docs/cli/endpoint-status.mdx@@ -61,7 +61,7 @@ Status includes:- Endpoint diagnostics- Destination configuration in JSON output, including Splunk HEC or Falcon LogScale HEC endpoint, index, source, and sourcetype when configured- Last Beacon event in the runtime log, when present-- Asymptote managed ingest: whether this endpoint is connected, the organization and device id, forwarder service state, whether the device key is still accepted by the ingest service (`valid`, `revoked`, or `unknown` when offline), and the disk buffer size. In `--json` this is the `managed_ingest` object; the device key itself is never included.+- Asymptote managed ingest: whether this endpoint is connected, the organization and device id, forwarder service state, whether the device key is still accepted by the ingest service (`valid`, `revoked`, or `unknown` when offline), and the disk buffer size. In `--json` this is the `managed_ingest` object; the device key itself is never included. The line reports the connection for the install mode you asked about (`--user` or `--system`), even when the collector view switches to the system install because it holds the OTLP ports.When Splunk HEC is configured, `--json` includes a `destinations.splunk_hec` object with `configured: true` and the non-secret destination settings. When Falcon LogScale HEC is configured, `--json` includes `destinations.falcon_hec` with the same non-secret fields. HEC tokens are not printed. File-based destinations such as Wazuh, Elastic, Datadog, Sumo Logic, Rapid7, Microsoft Sentinel, and AWS S3 validate against the configured runtime log path and their generated shipper configuration.diff --git a/docs/cli/endpoint.mdx b/docs/cli/endpoint.mdxindex 6bf1dca1..baaf7438 100644--- a/docs/cli/endpoint.mdx+++ b/docs/cli/endpoint.mdx@@ -25,6 +25,9 @@ beacon endpoint [command]<span id="beacon-endpoint-config" /><span id="beacon-endpoint-onboarding" /><span id="beacon-endpoint-fx" />+<span id="beacon-endpoint-connect" />+<span id="beacon-endpoint-disconnect" />+<span id="beacon-endpoint-asymptote" /><Columns cols={2}><Card title="beacon endpoint install" icon="download" href="/cli/endpoint-install">@@ -33,6 +36,12 @@ beacon endpoint [command]<Card title="beacon endpoint status" icon="circle-info" href="/cli/endpoint-status">Show collector, service, harness, diagnostic, and runtime log status.</Card>+ <Card title="beacon endpoint connect" icon="link" href="/cli/endpoint-connect">+ Approve this device in the Asymptote dashboard and start the Vector forwarder.+ </Card>+ <Card title="beacon endpoint disconnect" icon="link-slash" href="/cli/endpoint-connect">+ Stop the Asymptote forwarder and remove the local device key.+ </Card><Card title="beacon endpoint doctor" icon="stethoscope" href="/cli/endpoint-doctor">Run local endpoint health checks with pass/fail exit behavior.</Card>@@ -51,6 +60,9 @@ beacon endpoint [command]<Card title="beacon endpoint fx" icon="rotate" href="/cli/endpoint-fx">Collect telemetry from fx session records on this machine.</Card>+ <Card title="beacon endpoint asymptote" icon="tower-broadcast" href="/cli/asymptote">+ Generate the Asymptote forwarding pack for running Vector by hand.+ </Card><Card title="beacon scan" icon="magnifying-glass" href="/cli/scan">Run threat-detection rules over local endpoint telemetry.</Card>diff --git a/docs/cli/hooks.mdx b/docs/cli/hooks.mdxindex 37af5558..6accab25 100644--- a/docs/cli/hooks.mdx+++ b/docs/cli/hooks.mdx@@ -431,7 +431,7 @@ If Hermes telemetry is missing, confirm `~/.hermes/config.yaml` contains commandBeacon merges its hooks into Qwen Code's own `settings.json`: `~/.qwen/settings.json` for user-level installs, `./.qwen/settings.json` for project-level installs. Unrelated top-level keys and non-Beacon hooks in the same event group are preserved, and a re-install replaces Beacon's own entries instead of adding a second copy. Beacon identifies its entries by the `--platform qwen` argument in the hook command, since it has no file of its own in `~/.qwen` to stamp.-Qwen Code is a Gemini CLI fork without Gemini's OpenTelemetry export, so hooks are the only collection path for this runtime. `beacon endpoint install --harness qwen` fails with a message pointing here rather than appearing to succeed.+Qwen Code is a Gemini CLI fork without Gemini's OpenTelemetry export, so hooks are the only collection path for this runtime. `beacon endpoint install --harness qwen` installs these same hooks and writes `~/.qwen/settings.json`.Two Qwen-specific details are worth knowing before hand-editing the file:diff --git a/docs/cli/index.mdx b/docs/cli/index.mdxindex 7af6b541..3c193818 100644--- a/docs/cli/index.mdx+++ b/docs/cli/index.mdx@@ -118,6 +118,7 @@ Configure provider-managed cloud agent telemetry setup helpers.| [`beacon cloud cursor print-setup`](/cli/cloud-cursor-print-setup) | Print a Cursor cloud agent binary setup script. || [`beacon cloud cursor print-hooks`](/cli/cloud-cursor-print-hooks) | Print Cursor project hook settings to commit for cloud agents. || [`beacon cloud gcs setup`](/cli/cloud-gcs-setup) | Create or print GCS setup commands for cloud-agent telemetry. |+| [`beacon cloud s3 setup`](/cli/cloud-s3-setup) | Create or print S3 setup commands for cloud-agent telemetry. |## beacon mcp@@ -153,7 +154,9 @@ Manage the local endpoint agent and inspect supported agent harness telemetry.| [`beacon endpoint bundle-diagnostics`](/cli/endpoint-bundle-diagnostics) | Write a redacted local diagnostics bundle for support and troubleshooting. || [`beacon endpoint repair`](/cli/endpoint-repair) | Repair Beacon endpoint service files, telemetry configuration, and optional collector forwarding destinations. || [`beacon endpoint uninstall`](/cli/endpoint-uninstall) | Remove Beacon endpoint service files, with an option to keep local logs. |+| [`beacon endpoint update`](/cli/upgrade#self-updating-endpoint-packages) | Check for, enable, or apply signed endpoint package updates. || [`beacon endpoint config`](/cli/endpoint-config) | Inspect, validate, and update endpoint configuration. |+| [`beacon endpoint onboarding`](/cli/endpoint-onboarding) | Show, reset, or resend the one-time onboarding record. || [`beacon endpoint dashboard`](/cli/dashboard#beacon-endpoint-dashboard) | Run the local dashboard over Beacon runtime logs for endpoint inspection. || [`beacon endpoint wazuh`](/cli/wazuh) | Configure Wazuh ingestion for Beacon endpoint events. || [`beacon endpoint elastic`](/cli/elastic) | Generate Elastic content and run a local Elasticsearch, Kibana, and Filebeat validation stack. |@@ -164,7 +167,9 @@ Manage the local endpoint agent and inspect supported agent harness telemetry.| [`beacon endpoint cloudwatch`](/cli/cloudwatch) | Generate AWS CloudWatch Logs forwarding content for Beacon endpoint events. || [`beacon endpoint s3`](/cli/s3) | Generate AWS S3 forwarding content for Beacon endpoint events. || [`beacon endpoint gcs`](/cli/gcs) | Generate Google Cloud Storage forwarding content for Beacon endpoint events. |+| [`beacon endpoint asymptote`](/cli/asymptote) | Generate the Vector forwarding pack for Asymptote managed ingest and write validation events. || [`beacon endpoint hooks`](/cli/hooks) | Manage supported hook-based endpoint telemetry. |+| [`beacon endpoint fx`](/cli/endpoint-fx) | Collect endpoint telemetry from fx session records on this machine. || [`beacon endpoint integrations openclaw`](/cli/openclaw) | Set up and validate OpenClaw Gateway OTLP export. || [`beacon endpoint integrations claude-cowork`](/cli/claude-cowork) | Set up and validate Claude Cowork OTLP export. |@@ -308,6 +313,20 @@ Generate Google Cloud Storage forwarding content and validation events for Beaco| [`beacon endpoint gcs install-pack`](/cli/gcs#beacon-endpoint-gcs-install-pack) | Generate Google Cloud Storage forwarding content into a directory. || [`beacon endpoint gcs validate`](/cli/gcs#beacon-endpoint-gcs-validate) | Write and describe a known-good Beacon Google Cloud Storage validation event. |+## beacon endpoint asymptote++```bash title="Command syntax"+beacon endpoint asymptote [command]+```++Generate the Vector forwarding pack that sends Beacon endpoint events to Asymptote managed ingest, and write validation events.++| Command | Description |+|---------|-------------|+| [`beacon endpoint asymptote print-config`](/cli/asymptote#beacon-endpoint-asymptote-print-config) | Print the Vector forwarding config for the configured runtime log. |+| [`beacon endpoint asymptote install-pack`](/cli/asymptote#beacon-endpoint-asymptote-install-pack) | Write the Asymptote forwarding pack to a directory. |+| [`beacon endpoint asymptote validate`](/cli/asymptote#beacon-endpoint-asymptote-validate) | Write and describe a known-good Beacon Asymptote validation event. |+## beacon endpoint hooks```bash title="Command syntax"diff --git a/docs/security/endpoint-operations.mdx b/docs/security/endpoint-operations.mdxindex 929aa98f..5fa0f26e 100644--- a/docs/security/endpoint-operations.mdx+++ b/docs/security/endpoint-operations.mdx@@ -92,7 +92,7 @@ local-only.## Uninstall guarantees-`beacon endpoint uninstall` unloads the local Beacon service and removes managed endpoint files. Beacon removes files listed in its install manifest, including managed config, collector config, and service files. Unless `--keep-logs` is set, it also removes the configured runtime JSONL log. A connected endpoint's Asymptote forwarder service and `asymptote/` directory (Vector config, buffer, enrollment record, device key) are removed too; `beacon endpoint disconnect` does only that part.+`beacon endpoint uninstall` unloads the local Beacon service and removes managed endpoint files. Beacon removes files listed in its install manifest, including managed config, collector config, and service files. Unless `--keep-logs` is set, it also removes the configured runtime JSONL log. A connected endpoint's Asymptote forwarder service and `asymptote/` directory (Vector config, buffer, enrollment record, device key) are removed too, except that `--keep-config` keeps the enrollment record and device key; `beacon endpoint disconnect` does only that part.Use retention flags when you intentionally want to preserve evidence or configuration:diff --git a/docs/support/troubleshooting.mdx b/docs/support/troubleshooting.mdxindex ee44f48c..66afbb3c 100644--- a/docs/support/troubleshooting.mdx+++ b/docs/support/troubleshooting.mdx@@ -54,6 +54,9 @@ description: "Solutions for common issues when setting up and using Asymptote."After uninstalling hooks, restart the affected agent or IDE so new sessions pick up the updated hook configuration. See the [hook command docs](/cli/hooks#beacon-endpoint-hooks-uninstall) for supported harness names and flags.</Accordion>+ <Accordion title="beacon endpoint install fails with Collector ports are not listening">+ A user-mode collector cannot run beside a system-mode one, because the collector health-check port `127.0.0.1:13133` is fixed, so the install rolls back; run `beacon endpoint install --user --no-start` or uninstall the system endpoint first. Tracked as [GitHub issue #447](https://github.com/Asymptote-Labs/agent-beacon/issues/447).+ </Accordion><Accordion title="Endpoint package self-update is not running">For signed macOS package installs, self-update is off by default. Check theconfigured mode, updater LaunchDaemon state, and local update events: