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
---
title: "beacon endpoint s3"
description: "Generate AWS S3 forwarding content and validation events for Beacon endpoint events."
---
## Forwarding command
Use `beacon endpoint s3` to generate AWS S3 forwarding content for Beacon endpoint events. The generated pack keeps Beacon as a local JSONL producer and helps your customer-managed Vector agent upload `runtime.jsonl` to an S3 bucket as gzip-compressed NDJSON.
Beacon does not store AWS credentials, profiles, IAM roles, bucket policies, lifecycle rules, or encryption settings in endpoint configuration. Keep those values in AWS, Vector, endpoint-management policy, or deployment tooling. For packaged macOS MDM deployments, the managed S3 helper can persist MDM-injected AWS provider-chain environment variables to the root-owned Vector environment file used by launchd.
```bash title="Command syntax"
beacon endpoint s3 [command]
```
## Commands
<Columns cols={2}>
<Card title="beacon endpoint s3 print-config" icon="file-lines" href="#beacon-endpoint-s3-print-config">
Print a one-shot AWS CLI script that uploads the current logs to S3.
</Card>
<Card title="beacon endpoint s3 install-pack" icon="box-archive" href="#beacon-endpoint-s3-install-pack">
Write AWS S3 forwarding content to a directory.
</Card>
<Card title="beacon endpoint s3 validate" icon="check" href="#beacon-endpoint-s3-validate">
Write and describe a Beacon AWS S3 validation event.
</Card>
</Columns>
## Runtime log paths
| Mode | Path |
|------|------|
| User mode | `~/.beacon/endpoint/logs/runtime.jsonl` |
| System mode | `/var/log/beacon-agent/runtime.jsonl` |
## beacon endpoint s3 print-config
`beacon endpoint s3 print-config` prints a smoke-test script. The script uses the AWS CLI to copy the current runtime and inventory logs, once, to `<prefix>/runtime/smoke-tests/` and `<prefix>/inventory/smoke-tests/` in your bucket. Use it to check bucket access and IAM before you set up continuous forwarding. For the Vector configuration, use [`install-pack`](#beacon-endpoint-s3-install-pack).
```bash title="Print the smoke-test script"
beacon endpoint s3 print-config
```
### Examples
Print the script for the default per-user Beacon install:
```bash title="Print the script for the default per-user Beacon install"
beacon endpoint s3 print-config
```
Print the script for a system-mode MDM deployment:
```bash title="Print the script for a system-mode MDM deployment"
sudo /opt/beacon/bin/beacon endpoint s3 print-config --system
```
Print the script for a custom runtime log:
```bash title="Print the script for a custom runtime log"
beacon endpoint s3 print-config --log-path /path/to/runtime.jsonl
```
### Flags
| Flag | Description |
|------|-------------|
| `--user` | Use per-user endpoint paths. Enabled by default |
| `--system` | Use system endpoint paths and launch daemon |
| `--log-path <path>` | Runtime JSONL log path |
## beacon endpoint s3 install-pack
`beacon endpoint s3 install-pack` writes AWS S3 forwarding content to a directory.
```bash title="Generate the integration pack"
beacon endpoint s3 install-pack --output ./beacon-s3-pack
```
The pack includes setup instructions, a one-shot AWS CLI smoke-test script, a Vector `aws_s3` forwarding template, and sample Beacon endpoint events.
The generated Vector template preserves each Beacon event's canonical
`gen_ai.usage` payload and also flattens token and runtime-reported cost fields
to top-level JSON columns for downstream analytics: `input_tokens`,
`output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`,
`reasoning_output_tokens`, and `cost_usd`. The packaged macOS S3 forwarder that
MDM deployments use doesn't add these columns; its objects carry `gen_ai.usage`
only.
### Examples
Generate a content pack for the default per-user install:
```bash title="Generate a content pack for the default per-user install"
beacon endpoint s3 install-pack --output ./beacon-s3-pack
```
Generate a content pack for a system-mode deployment:
```bash title="Generate a content pack for a system-mode deployment"
sudo /opt/beacon/bin/beacon endpoint s3 install-pack \
--system \
--output ./beacon-s3-pack
```
Generate a content pack for a custom runtime log:
```bash title="Generate a content pack for a custom runtime log"
beacon endpoint s3 install-pack \
--output ./beacon-s3-pack \
--log-path /path/to/runtime.jsonl
```
### Flags
| Flag | Description |
|------|-------------|
| `--output <dir>` | Output directory for the AWS S3 content pack. Defaults to `beacon-s3-pack` |
| `--user` | Use per-user endpoint paths. Enabled by default |
| `--system` | Use system endpoint paths and launch daemon |
| `--log-path <path>` | Runtime JSONL log path |
## beacon endpoint s3 validate
`beacon endpoint s3 validate` writes a Beacon validation event to the runtime JSONL log and prints the expected AWS S3 validation fields and follow-up AWS CLI checks.
```bash title="Run the validation check"
beacon endpoint s3 validate
```
### Examples
Write a validation event for the default per-user install:
```bash title="Write a validation event for the default per-user install"
beacon endpoint s3 validate
```
Write a validation event for a system-mode deployment:
```bash title="Write a validation event for a system-mode deployment"
sudo /opt/beacon/bin/beacon endpoint s3 validate --system
```
Write a validation event to a custom runtime log:
```bash title="Write a validation event to a custom runtime log"
beacon endpoint s3 validate --log-path /path/to/runtime.jsonl
```
The validation command writes the local event only. The forwarder uploads in batches, so allow up to five minutes, then confirm delivery with AWS tooling. The event lands under `runtime/`:
```text
aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/" --recursive --region "$AWS_REGION"
aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" - --region "$AWS_REGION" | gzip -dc | grep "Beacon endpoint S3 validation event"
```
Expected validation fields:
```text
vendor=beacon product=endpoint-agent destination.type=s3 destination.mode=aws_s3_jsonl
```
### Flags
| Flag | Description |
|------|-------------|
| `--user` | Use per-user endpoint paths. Enabled by default |
| `--system` | Use system endpoint paths and launch daemon |
| `--log-path <path>` | Runtime JSONL log path |
## macOS MDM credential injection
For a managed macOS package, run `/opt/beacon/jamf/claude/s3/repair-hooks-and-forwarder.sh` from MDM or a root shell with destination settings in the environment. The helper writes non-secret forwarding settings and any set AWS provider-chain variables to `/Library/Application Support/Beacon/Forwarders/s3-vector.env` with mode `0600`, then starts `com.beacon.endpoint.s3-forwarder`.
Supported provider-chain variables include `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_PROFILE`, `AWS_SHARED_CREDENTIALS_FILE`, `AWS_CONFIG_FILE`, `AWS_WEB_IDENTITY_TOKEN_FILE`, and `AWS_ROLE_ARN`. These values are not written to Beacon endpoint config or `s3-vector.toml`.
## Related
<Columns cols={2}>
<Card title="AWS S3 with Terraform" icon="bucket" href="/log-forwarding/aws-s3-terraform">
Create the bucket and write-only IAM user with Terraform.
</Card>
<Card title="Beacon with Fleet and S3" icon="bucket" href="/guides/fleet-s3-mdm">
Fleet software install, self-updates, and Vector forwarding to S3.
</Card>
<Card title="Object storage forwarding" icon="chart-line" href="/guides/macos-object-storage-system">
Configure Vector forwarding from Beacon JSONL into AWS S3.
</Card>
<Card title="Log forwarding" icon="tower-broadcast" href="/log-forwarding">
Review forwarding patterns and validation steps.
</Card>
<Card title="Endpoint agent" icon="desktop" href="/cli/endpoint">
Install and inspect the local endpoint agent.
</Card>
<Card title="Endpoint event schema" icon="code" href="/telemetry-schema/event-schema">
Review normalized Beacon JSONL fields and example events.
</Card>
</Columns>