Skip to content

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

Add Jamf S3 setup guide

shukieshah7577ec881ae6
diff --git a/docs/docs.json b/docs/docs.json
index 314c43f4..5b45b0cf 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -195,6 +195,7 @@
"pages": [
"mdm/jamf",
"mdm/jamf/claude",
+ "guides/jamf-s3-mdm",
"mdm/fleet"
]
},
diff --git a/docs/guides/jamf-s3-mdm.mdx b/docs/guides/jamf-s3-mdm.mdx
new file mode 100644
index 00000000..097e068d
--- /dev/null
+++ b/docs/guides/jamf-s3-mdm.mdx
@@ -0,0 +1,453 @@
+---
+title: "Deploy Beacon With Jamf And S3"
+description: "Self-serve Jamf Pro setup for Beacon endpoint telemetry, Claude Code hooks, inventory snapshots, and AWS S3 forwarding"
+---
+
+## Overview
+
+Use this guide when you want a Jamf Pro policy to install Beacon for macOS users and forward both runtime and inventory telemetry to AWS S3 without asking end users to configure anything manually.
+
+The end state is:
+
+- Beacon is installed under `/opt/beacon`.
+- The system endpoint collector runs as a LaunchDaemon.
+- Claude Code hooks are installed for the logged-in console user.
+- Runtime activity is written to `/var/log/beacon-agent/runtime.jsonl`.
+- Agent config inventory is written to `/var/log/beacon-agent/inventory_state.jsonl`.
+- Vector forwards both JSONL streams to S3:
+ - `s3://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/...`
+ - `s3://<bucket>/<prefix>/inventory/date=YYYY-MM-DD/...`
+
+```mermaid
+flowchart LR
+ JamfPolicy[Jamf policy] --> Package[Beacon pkg]
+ JamfPolicy --> Helper[repair-hooks-and-forwarder.sh]
+ Package --> Beacon["/opt/beacon"]
+ Helper --> Collector[Endpoint collector]
+ Helper --> Hooks[Claude Code hooks]
+ Hooks --> RuntimeLog["runtime.jsonl"]
+ Hooks --> InventoryLog["inventory_state.jsonl"]
+ RuntimeLog --> Vector[Vector LaunchDaemon]
+ InventoryLog --> Vector
+ Vector --> S3[AWS S3]
+```
+
+## Prerequisites
+
+Before creating the Jamf policy, prepare:
+
+- A signed and notarized Beacon endpoint `.pkg` that includes `/opt/beacon/bin/vector`.
+- A target AWS S3 bucket.
+- An S3 prefix root such as `beacon`, `beacon-prod`, or `beacon-e2e`.
+- AWS credentials or a role available to the Jamf policy at install time.
+- `s3:PutObject` permission for the selected bucket prefix.
+- Claude Code installed on the target Mac.
+
+Use a root prefix. Do not include `runtime` or `inventory` in the value:
+
+```bash
+BEACON_S3_PREFIX="beacon-prod" # good
+BEACON_S3_PREFIX="beacon-prod/runtime" # avoid
+```
+
+The helper normalizes old prefixes ending in `/runtime` or `/inventory`, but new deployments should use the root prefix.
+
+## AWS Permission
+
+Use a bucket policy or IAM policy scoped to the Beacon prefix. Example:
+
+```json
+{
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": ["s3:PutObject"],
+ "Resource": "arn:aws:s3:::example-security-logs/beacon-prod/*"
+ }
+ ]
+}
+```
+
+Beacon does not store AWS credentials in endpoint configuration. The Jamf helper persists only the AWS provider-chain values it receives into a root-owned Vector environment file:
+
+```text
+/Library/Application Support/Beacon/Forwarders/s3-vector.env
+```
+
+That file is mode `0600` and is sourced by the Vector LaunchDaemon wrapper.
+
+## Jamf Policy Setup
+
+Create a Jamf Pro policy scoped to the target Macs.
+
+### 1. Install The Beacon Package
+
+Add the signed Beacon endpoint package to the policy.
+
+The package installs:
+
+```text
+/opt/beacon/bin/beacon
+/opt/beacon/bin/beacon-otelcol
+/opt/beacon/bin/vector
+/opt/beacon/jamf/claude/common/repair-hooks.sh
+/opt/beacon/jamf/claude/s3/install-forwarder.sh
+/opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh
+/opt/beacon/jamf/claude/s3/run-forwarder.sh
+```
+
+### 2. Run The Combined Jamf Helper
+
+Add a script step after the package install:
+
+```bash
+/opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh
+```
+
+Pass the S3 settings and AWS provider values through Jamf script environment variables or Jamf secret injection:
+
+```bash
+BEACON_S3_BUCKET="example-security-logs"
+AWS_REGION="us-west-2"
+BEACON_S3_PREFIX="beacon-prod"
+AWS_ACCESS_KEY_ID="..."
+AWS_SECRET_ACCESS_KEY="..."
+```
+
+If you use temporary credentials, also pass:
+
+```bash
+AWS_SESSION_TOKEN="..."
+```
+
+If you use AWS profiles or shared credential files, pass the relevant provider-chain variables instead:
+
+```bash
+AWS_PROFILE="..."
+AWS_SHARED_CREDENTIALS_FILE="..."
+AWS_CONFIG_FILE="..."
+AWS_WEB_IDENTITY_TOKEN_FILE="..."
+AWS_ROLE_ARN="..."
+```
+
+## What The Helper Does
+
+The combined helper performs all endpoint and forwarding setup:
+
+- Repairs the Beacon system endpoint.
+- Starts `com.beacon.endpoint.collector`.
+- Prepares:
+ - `/var/log/beacon-agent/runtime.jsonl`
+ - `/var/log/beacon-agent/inventory_state.jsonl`
+ - `/var/log/beacon-agent/inventory-state.json`
+- Grants the console user append access for hook-written logs.
+- Installs Claude Code hooks for the interactive console user.
+- Writes:
+ - `/Library/Application Support/Beacon/Forwarders/s3-vector.toml`
+ - `/Library/Application Support/Beacon/Forwarders/s3-vector.env`
+ - `/Library/LaunchDaemons/com.beacon.endpoint.s3-forwarder.plist`
+- Starts `com.beacon.endpoint.s3-forwarder`.
+
+End users do not need to run any Beacon command or edit any local config.
+
+## Expected S3 Layout
+
+If you configure:
+
+```text
+BEACON_S3_BUCKET=example-security-logs
+BEACON_S3_PREFIX=beacon-prod
+```
+
+Beacon writes objects under:
+
+```text
+s3://example-security-logs/beacon-prod/runtime/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
+s3://example-security-logs/beacon-prod/inventory/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
+```
+
+Runtime objects contain agent activity from `runtime.jsonl`.
+
+Inventory objects contain `inventory.heartbeat` and `inventory.snapshot` events from `inventory_state.jsonl`.
+
+## Validate A Deployed Mac
+
+Run these commands on a target Mac after the Jamf policy completes.
+
+### Check Services
+
+```bash
+sudo launchctl print system/com.beacon.endpoint.collector
+sudo launchctl print system/com.beacon.endpoint.s3-forwarder
+```
+
+Both services should be `running`.
+
+### Check Local Files
+
+```bash
+ls -l /var/log/beacon-agent/runtime.jsonl
+ls -l /var/log/beacon-agent/inventory_state.jsonl
+ls -l /var/log/beacon-agent/inventory-state.json
+```
+
+### Check Vector Config
+
+```bash
+sudo grep -E 'runtime.jsonl|inventory_state.jsonl|runtime/date|inventory/date|read_from' \
+ "/Library/Application Support/Beacon/Forwarders/s3-vector.toml"
+```
+
+Expected:
+
+```text
+include = ["/var/log/beacon-agent/runtime.jsonl"]
+read_from = "${BEACON_VECTOR_READ_FROM:-end}"
+include = ["/var/log/beacon-agent/inventory_state.jsonl"]
+read_from = "beginning"
+key_prefix = "${BEACON_S3_PREFIX:-beacon}/runtime/date=%F/"
+key_prefix = "${BEACON_S3_PREFIX:-beacon}/inventory/date=%F/"
+```
+
+Runtime forwarding starts at the end of the runtime log so historical session activity is not backfilled when Vector is first installed.
+
+Inventory forwarding starts at the beginning of `inventory_state.jsonl` so the first inventory snapshot is not missed if the file was created before Vector began watching it.
+
+## Generate Test Events
+
+### Runtime Event
+
+Write a synthetic runtime validation event:
+
+```bash
+sudo /opt/beacon/bin/beacon endpoint test-event \
+ --system \
+ --log-path /var/log/beacon-agent/runtime.jsonl
+```
+
+### Inventory Event
+
+Write an inventory heartbeat and snapshot:
+
+```bash
+sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
+ --system \
+ --force \
+ --trigger manual \
+ --trigger-harness claude \
+ --working-dir /Users/Shared \
+ --log-path /var/log/beacon-agent/runtime.jsonl
+```
+
+Confirm both files have events:
+
+```bash
+tail -n 5 /var/log/beacon-agent/runtime.jsonl
+tail -n 5 /var/log/beacon-agent/inventory_state.jsonl
+```
+
+## Confirm S3 Delivery
+
+Vector batches uploads. Production configs use `timeout_secs = 300`, so allow up to five minutes unless you lower the batch timeout for a demo.
+
+```bash
+aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/" \
+ --recursive \
+ --region "$AWS_REGION"
+
+aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/inventory/" \
+ --recursive \
+ --region "$AWS_REGION"
+```
+
+Inspect the latest inventory object:
+
+```bash
+aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/inventory/date=<YYYY-MM-DD>/<object>.jsonl.gz" - \
+ --region "$AWS_REGION" | gzip -dc | grep 'inventory.snapshot'
+```
+
+## Live Demo Settings
+
+For a live demo, reduce the inventory TTL:
+
+```bash
+sudo python3 - <<'PY'
+import json
+from pathlib import Path
+
+path = Path("/Library/Application Support/Beacon/Endpoint/config.json")
+data = json.loads(path.read_text())
+data["inventory_heartbeat"] = {
+ "enabled": True,
+ "ttl_seconds": 5,
+ "runtimes": ["cursor", "claude_code"]
+}
+path.write_text(json.dumps(data, indent=2) + "\n")
+PY
+```
+
+Reduce Vector S3 batch timeout:
+
+```bash
+sudo python3 - <<'PY'
+from pathlib import Path
+
+path = Path("/Library/Application Support/Beacon/Forwarders/s3-vector.toml")
+text = path.read_text()
+text = text.replace("timeout_secs = 300", "timeout_secs = 5")
+path.write_text(text)
+PY
+```
+
+Restart the forwarder:
+
+```bash
+sudo launchctl bootout system/com.beacon.endpoint.s3-forwarder 2>/dev/null || true
+sudo launchctl bootstrap system /Library/LaunchDaemons/com.beacon.endpoint.s3-forwarder.plist
+```
+
+If launchd returns `Bootstrap failed: 5`, run Vector in the foreground for the demo:
+
+```bash
+sudo /opt/beacon/jamf/claude/s3/run-forwarder.sh
+```
+
+Keep that terminal open while generating runtime and inventory events.
+
+## Test A Live Skill And MCP Change
+
+Create a Claude Code skill:
+
+```bash
+mkdir -p ~/.claude/skills/beacon-live-skill
+cat > ~/.claude/skills/beacon-live-skill/SKILL.md <<'EOF'
+# Beacon Live Skill
+
+Harmless inventory validation skill.
+EOF
+```
+
+Add a Claude Code MCP server to top-level `mcpServers` in `~/.claude.json`:
+
+```json
+"beacon_live_mcp": {
+ "command": "node",
+ "args": ["-e", "process.exit(0)"],
+ "env": {
+ "BEACON_SMOKE_ENV": "present"
+ }
+}
+```
+
+Then force inventory:
+
+```bash
+sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
+ --system \
+ --force \
+ --trigger manual \
+ --trigger-harness claude \
+ --working-dir /Users/Shared \
+ --log-path /var/log/beacon-agent/runtime.jsonl
+```
+
+Confirm the local inventory event includes both names:
+
+```bash
+grep 'beacon-live-skill\|beacon_live_mcp' /var/log/beacon-agent/inventory_state.jsonl
+```
+
+After Vector flushes, the same names should appear in an object under the S3 `inventory/` prefix.
+
+## Restore Production Settings
+
+After a demo, restore the production TTL:
+
+```bash
+sudo python3 - <<'PY'
+import json
+from pathlib import Path
+
+path = Path("/Library/Application Support/Beacon/Endpoint/config.json")
+data = json.loads(path.read_text())
+data["inventory_heartbeat"] = {
+ "enabled": True,
+ "ttl_seconds": 86400,
+ "runtimes": ["cursor", "claude_code"]
+}
+path.write_text(json.dumps(data, indent=2) + "\n")
+PY
+```
+
+Regenerate the Vector config by rerunning the Jamf helper if you changed `timeout_secs` manually:
+
+```bash
+sudo env \
+ BEACON_S3_BUCKET="$BEACON_S3_BUCKET" \
+ AWS_REGION="$AWS_REGION" \
+ BEACON_S3_PREFIX="$BEACON_S3_PREFIX" \
+ AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" \
+ AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
+ /opt/beacon/jamf/claude/s3/install-forwarder.sh
+```
+
+## Troubleshooting
+
+### No S3 Objects
+
+Check the forwarder:
+
+```bash
+sudo launchctl print system/com.beacon.endpoint.s3-forwarder
+sudo tail -n 100 /tmp/com.beacon.endpoint.s3-forwarder.err
+```
+
+### Forwarder Is Not Loaded
+
+Load it manually:
+
+```bash
+sudo launchctl bootstrap system /Library/LaunchDaemons/com.beacon.endpoint.s3-forwarder.plist
+```
+
+If launchd remains opaque, run Vector in the foreground:
+
+```bash
+sudo /opt/beacon/jamf/claude/s3/run-forwarder.sh
+```
+
+### Credentials Are Missing
+
+Check the env file without exposing secrets:
+
+```bash
+sudo sh -c 'sed -E "s/(AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN|BEACON_S3_BUCKET|AWS_REGION|BEACON_S3_PREFIX)=.*/\1=<redacted>/" "/Library/Application Support/Beacon/Forwarders/s3-vector.env"'
+```
+
+### Inventory Is Empty
+
+Force inventory and inspect the local file:
+
+```bash
+sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
+ --system \
+ --force \
+ --trigger manual \
+ --trigger-harness claude \
+ --working-dir /Users/Shared \
+ --log-path /var/log/beacon-agent/runtime.jsonl
+
+tail -n 5 /var/log/beacon-agent/inventory_state.jsonl
+```
+
+### Claude Hooks Are Missing
+
+Fully restart Claude Code after the Jamf policy runs. Then inspect the user's Claude settings:
+
+```bash
+grep -n 'BEACON_ENDPOINT_CLI\|beacon-hooks' ~/.claude/settings.json
+```
+
+You should see commands that call the packaged Beacon hook binary.