Claude System Mode with S3

Overview

Use this guide for a single Mac where you want Beacon running in system mode, Claude Code telemetry enabled, and local Beacon JSONL logs forwarded to an S3 bucket. There is no MDM setup here. The end state is:

Beacon is installed under /opt/beacon from the signed and notarized GitHub Release package.
The system collector runs as com.beacon.endpoint.collector.
Claude Code hooks are installed for the logged-in user.
Runtime logs are written to /var/log/beacon-agent/runtime.jsonl.
Inventory logs are written to /var/log/beacon-agent/inventory_state.jsonl.
Bundled Vector forwards both streams to S3 under runtime/ and inventory/.

1. Prepare AWS

Create or choose an S3 bucket and a root prefix such as beacon-prod. Do not include runtime or inventory in the prefix; Beacon adds those folders.

Create an S3 bucket

Create the bucket that will receive Beacon endpoint logs. Replace the example bucket name and region with your values:

aws s3api create-bucket \
  --bucket example-security-logs \
  --region us-west-2 \
  --create-bucket-configuration LocationConstraint=us-west-2

If you already have a bucket, choose the root prefix Beacon should write under, for example beacon-prod.

Create an S3 policy

Name the IAM policy BeaconEndpointWriteOnly and give the credentials used by Vector permission to write under the selected prefix. Save this JSON as beacon-s3-write-only-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject"],
      "Resource": "arn:aws:s3:::example-security-logs/beacon-prod/*"
    }
  ]
}

Create the IAM policy:

aws iam create-policy \
  --policy-name BeaconEndpointWriteOnly \
  --policy-document file://beacon-s3-write-only-policy.json

If your bucket requires KMS or object tags, add the required kms:* or s3:PutObjectTagging permissions in AWS.

Create or choose IAM credentials

You get the access key and secret key from AWS IAM, but ideally use temporary credentials instead of long-lived access keys. For a quick setup:

Open the AWS Console.
Go to IAM.
Go to Users.
Select the IAM user you want Vector to use, or create one named beacon-endpoint-writer.
Attach the BeaconEndpointWriteOnly policy to that IAM user.
Open the Security credentials tab.
Under Access keys, click Create access key.
Choose the use case, such as Command Line Interface (CLI).
AWS will show AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

AWS only shows the secret access key once. Copy it immediately or download the .csv. For a quick local setup, have these values ready:

export BEACON_S3_BUCKET="example-security-logs"
export BEACON_S3_PREFIX="beacon-prod"
export AWS_REGION="us-west-2"

# Use temporary or managed credentials when possible.
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="" # optional

Beacon does not store these secrets in endpoint configuration. The helper writes the AWS provider-chain values you pass to Vector’s root-owned env file at /Library/Application Support/Beacon/Forwarders/s3-vector.env with mode 0600. You can also use normal AWS provider-chain settings such as AWS_PROFILE, AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILE, AWS_WEB_IDENTITY_TOKEN_FILE, or AWS_ROLE_ARN instead of raw access keys.

2. Install The Package

Download and install the latest Apple Silicon endpoint package from GitHub Releases:

tmpdir="$(mktemp -d)"
gh release download \
  --repo Asymptote-Labs/agent-beacon \
  --pattern 'BeaconEndpointAgent-*-arm64.pkg' \
  --dir "$tmpdir"

sudo installer -pkg "$tmpdir"/BeaconEndpointAgent-*-arm64.pkg -target /
/opt/beacon/bin/beacon version

If you do not use the GitHub CLI, download the latest BeaconEndpointAgent-*-arm64.pkg asset from the release page and run the same sudo installer command against that file. The package installs /opt/beacon/bin/beacon, /opt/beacon/bin/beacon-otelcol, /opt/beacon/bin/vector, and the S3 helper scripts.

3. Configure Beacon And S3

Run the packaged helper once from an interactive login session. Keep Claude Code closed while this runs.

sudo env \
  BEACON_S3_BUCKET="$BEACON_S3_BUCKET" \
  BEACON_S3_PREFIX="$BEACON_S3_PREFIX" \
  BEACON_S3_STORAGE_CLASS="STANDARD" \
  AWS_REGION="$AWS_REGION" \
  AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" \
  AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
  AWS_SESSION_TOKEN="${AWS_SESSION_TOKEN:-}" \
  /opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh

This starts the Beacon collector, installs Claude hooks for the current console user, writes the Vector S3 config, and starts com.beacon.endpoint.s3-forwarder. Restart Claude Code before testing a real Claude session.

4. Verify Locally

Check the two services:

sudo launchctl print system/com.beacon.endpoint.collector
sudo launchctl print system/com.beacon.endpoint.s3-forwarder

Check Beacon status and local logs:

sudo /opt/beacon/bin/beacon endpoint status --system
ls -l /var/log/beacon-agent/runtime.jsonl /var/log/beacon-agent/inventory_state.jsonl

Write a validation event:

sudo /opt/beacon/bin/beacon endpoint s3 validate --system
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 events landed locally:

tail -n 5 /var/log/beacon-agent/runtime.jsonl
tail -n 5 /var/log/beacon-agent/inventory_state.jsonl

5. Verify S3

Vector batches uploads, so allow up to five minutes.

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 a recent object:

aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/date=<YYYY-MM-DD>/<object>.jsonl.gz" - \
  --region "$AWS_REGION" | gzip -dc | grep "Beacon endpoint S3 validation event"

Expected layout:

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

Troubleshooting

Vector Is Not Starting

Check launchd and Vector stderr:

sudo launchctl print system/com.beacon.endpoint.s3-forwarder
sudo tail -n 100 /tmp/com.beacon.endpoint.s3-forwarder.err

Run Vector in the foreground to see the real error:

sudo /opt/beacon/jamf/claude/s3/run-forwarder.sh

Common causes are a missing /opt/beacon/bin/vector, a malformed env file, missing AWS credentials, or an S3 bucket/prefix/IAM mismatch. Re-run the helper after fixing the environment.

Port 4137 Or 4317 Is Already In Use

Beacon’s default OTLP ports are 4317 for gRPC and 4318 for HTTP. If setup reports a port conflict, first retry the same command once. A transient launchd or collector startup race can briefly surface as “address already in use” and then succeed on the next run. If the retry fails, identify the process:

sudo lsof -nP -iTCP:4317 -sTCP:LISTEN
sudo lsof -nP -iTCP:4318 -sTCP:LISTEN
sudo lsof -nP -iTCP:4137 -sTCP:LISTEN # only if the error names 4137

Either stop the conflicting process or choose alternate Beacon ports and re-run setup:

sudo env \
  BEACON_OTLP_GRPC_PORT="44317" \
  BEACON_OTLP_HTTP_PORT="44318" \
  BEACON_S3_BUCKET="$BEACON_S3_BUCKET" \
  BEACON_S3_PREFIX="$BEACON_S3_PREFIX" \
  AWS_REGION="$AWS_REGION" \
  AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" \
  AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
  AWS_SESSION_TOKEN="${AWS_SESSION_TOKEN:-}" \
  /opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh

Restart Claude Code after changing ports.

No S3 Objects Appear

First wait five minutes. Then check that Vector has the expected non-secret settings:

sudo sh -c 'sed -E "s/(AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN)=.*/\1=<redacted>/" "/Library/Application Support/Beacon/Forwarders/s3-vector.env"'
sudo grep -E 'runtime.jsonl|inventory_state.jsonl|key_prefix|read_from' \
  "/Library/Application Support/Beacon/Forwarders/s3-vector.toml"

Then confirm IAM allows s3:PutObject for s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/*, the AWS region matches the bucket, and the validation event was written after Vector started. Runtime forwarding starts at the end of the file to avoid backfilling old runtime events.

Claude Hooks Are Missing

Run the helper while an interactive user is logged in, then restart Claude Code. Check the user’s Claude settings:

grep -n 'BEACON_ENDPOINT_CLI\|beacon-hooks' ~/.claude/settings.json

If nothing appears, re-run:

sudo env \
  BEACON_S3_BUCKET="$BEACON_S3_BUCKET" \
  BEACON_S3_PREFIX="$BEACON_S3_PREFIX" \
  AWS_REGION="$AWS_REGION" \
  AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" \
  AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
  AWS_SESSION_TOKEN="${AWS_SESSION_TOKEN:-}" \
  /opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh

Launchd Says Bootstrap Failed: 5

Verify the files exist and are executable/readable:

ls -l /opt/beacon/bin/beacon /opt/beacon/bin/beacon-otelcol /opt/beacon/bin/vector
ls -l /Library/LaunchDaemons/com.beacon.endpoint.collector.plist
ls -l /Library/LaunchDaemons/com.beacon.endpoint.s3-forwarder.plist

Clear stale launchd state and run the helper again:

sudo launchctl bootout system/com.beacon.endpoint.collector 2>/dev/null || true
sudo launchctl bootout system/com.beacon.endpoint.s3-forwarder 2>/dev/null || true

Get Started

Deploy Asymptote

How Asymptote Works

Manage Asymptote

Agent Harness Integrations

For Security & IT Teams

Claude System Mode with S3

Overview

1. Prepare AWS

Create an S3 bucket

Create an S3 policy

Create or choose IAM credentials

2. Install The Package

3. Configure Beacon And S3

4. Verify Locally

5. Verify S3

Troubleshooting

Vector Is Not Starting

Port 4137 Or 4317 Is Already In Use

No S3 Objects Appear

Claude Hooks Are Missing

Launchd Says Bootstrap Failed: 5

​Overview

​1. Prepare AWS

​Create an S3 bucket

​Create an S3 policy

​Create or choose IAM credentials

​2. Install The Package

​3. Configure Beacon And S3

​4. Verify Locally

​5. Verify S3

​Troubleshooting

​Vector Is Not Starting

​Port 4137 Or 4317 Is Already In Use

​No S3 Objects Appear

​Claude Hooks Are Missing

​Launchd Says Bootstrap Failed: 5

Overview

1. Prepare AWS

Create an S3 bucket

Create an S3 policy

Create or choose IAM credentials

2. Install The Package

3. Configure Beacon And S3

4. Verify Locally

5. Verify S3

Troubleshooting

Vector Is Not Starting

Port 4137 Or 4317 Is Already In Use

No S3 Objects Appear

Claude Hooks Are Missing

Launchd Says Bootstrap Failed: 5