Claude Code, Codex, and Cursor with Jamf and GCS

Use this guide to install Beacon on your Macs with Jamf Pro and send the AI agent activity it records to a Cloud Storage bucket you own. People using the Macs don’t have to do anything.

What you’ll have

Every Mac in scope gets:

Beacon, installed from the signed package, recording what Claude Code, Codex, and Cursor do for the person logged in: prompts, commands and their output, tool and MCP calls, file edits, approvals, and token usage, where each agent exposes them.
An inventory of the Mac’s AI agents, MCP servers, and skills, taken every six hours.
A forwarder that uploads both to your bucket with a key that can only add new objects below your prefix:

gs://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<unix-time>-<uuid>.jsonl
gs://<bucket>/<prefix>/inventory/date=YYYY-MM-DD/<unix-time>-<uuid>.jsonl

Each object is newline-delimited JSON, one event per line, with the fields in the telemetry schema. Agent activity reaches the bucket within five minutes. Nothing else leaves the Mac, and the agents’ hooks never use the network.

Before you start

You need	For
Jamf Pro, with rights to add packages, scripts, and policies	Steps 4 and 5
Apple Silicon Macs	The Beacon package is built for Apple Silicon only
A Google Cloud project where you can create a bucket and service accounts	Step 1
Permission to create a service-account key in that project	Step 2
A Mac with gcloud, and Terraform 1.5 or later if you use Terraform	Steps 1 to 3

To see what Beacon records before you roll it out, download the package as in step 3 and install it on one Mac with sudo installer -pkg BeaconEndpointAgent-<version>-arm64.pkg -target /.

1. Set up Google Cloud

Pick a root prefix such as beacon-prod. Beacon adds runtime/ and inventory/ below it, so don’t put either in the prefix.

Terraform
gcloud

Beacon’s Terraform module creates a new bucket just for Beacon, a writer service account that can only create objects below your prefix, and a read-only service account. Create a main.tf in a new directory and change the project, location, bucket name, and prefix:

main.tf

provider "google" {
  project = "<project-id>"
}

module "beacon_gcs" {
  source = "github.com/asymptote-labs/agent-beacon//terraform/gcs?ref=v1.3.38"

  project       = "<project-id>"
  location      = "<region>" # for example us-central1
  bucket_name   = "<globally-unique-bucket>"
  prefix        = "beacon-prod"
  create_reader = true
}

output "bucket_name" {
  value = module.beacon_gcs.bucket_name
}

output "prefix" {
  value = module.beacon_gcs.prefix
}

output "writer_email" {
  value = module.beacon_gcs.writer_email
}

output "reader_email" {
  value = module.beacon_gcs.reader_email
}

terraform init
terraform apply

Review the plan and type yes. It’s working when the apply ends with Apply complete! Resources: 7 added, 0 changed, 0 destroyed. and prints the four outputs.Save the values for the next steps:

export GCP_PROJECT="<project-id>"
export BEACON_GCS_BUCKET="$(terraform output -raw bucket_name)"
export BEACON_GCS_PREFIX="$(terraform output -raw prefix)"
export BEACON_GCS_WRITER_EMAIL="$(terraform output -raw writer_email)"
export BEACON_GCS_READER_EMAIL="$(terraform output -raw reader_email)"

For your own Cloud KMS key, object expiry, and other settings, see the module’s options.

Set your values:

export GCP_PROJECT="<project-id>"
export GCP_REGION="<region>"                 # for example us-central1
export BEACON_GCS_BUCKET="<globally-unique-bucket>"
export BEACON_GCS_PREFIX="beacon-prod"
export BEACON_GCS_WRITER_EMAIL="beacon-endpoint-writer@${GCP_PROJECT}.iam.gserviceaccount.com"
export BEACON_GCS_READER_EMAIL="beacon-endpoint-reader@${GCP_PROJECT}.iam.gserviceaccount.com"

Create the bucket and two service accounts:

gcloud services enable storage.googleapis.com iam.googleapis.com \
  --project "$GCP_PROJECT"

gcloud storage buckets create "gs://${BEACON_GCS_BUCKET}" \
  --project "$GCP_PROJECT" \
  --location "$GCP_REGION" \
  --uniform-bucket-level-access \
  --public-access-prevention

gcloud iam service-accounts create beacon-endpoint-writer \
  --project "$GCP_PROJECT" \
  --display-name "Beacon endpoint GCS writer"

gcloud iam service-accounts create beacon-endpoint-reader \
  --project "$GCP_PROJECT" \
  --display-name "Beacon endpoint GCS reader"

Give them access to the bucket. A new service account can take a few seconds to appear, so if a command says it does not exist, run it again.

# The writer can only create new objects below the prefix.
gcloud storage buckets add-iam-policy-binding "gs://${BEACON_GCS_BUCKET}" \
  --member "serviceAccount:${BEACON_GCS_WRITER_EMAIL}" \
  --role roles/storage.objectCreator \
  --condition "title=beacon-prefix-only,expression=resource.name.startsWith(\"projects/_/buckets/${BEACON_GCS_BUCKET}/objects/${BEACON_GCS_PREFIX}/\")"

# The reader can list and read everything in the bucket.
gcloud storage buckets add-iam-policy-binding "gs://${BEACON_GCS_BUCKET}" \
  --member "serviceAccount:${BEACON_GCS_READER_EMAIL}" \
  --role roles/storage.objectViewer \
  --condition=None

The writer can’t list, read, overwrite, or delete objects, or write outside the prefix. Turn on versioning, lifecycle rules, or your own encryption key as your policies require.

2. Create the writer key

The forwarder on each Mac signs in to Google Cloud with a key for the writer service account:

umask 077
gcloud iam service-accounts keys create ./beacon-gcs-writer.json \
  --project "$GCP_PROJECT" \
  --iam-account "$BEACON_GCS_WRITER_EMAIL"

It’s working when gcloud prints created key [...]. Keep the file for step 3, and don’t commit it or share it in chat or email.

If gcloud says Key creation is not allowed on this service account, your Google Cloud organization blocks service-account keys, which new organizations do by default. Ask someone with the Organization Policy Administrator role to allow keys in this project only:

gcloud resource-manager org-policies disable-enforce iam.disableServiceAccountKeyCreation \
  --project "$GCP_PROJECT"

The rest of your organization still blocks keys. The change takes a minute or two to apply, and then the command above works. To manage this exception with Terraform, see Allow service-account keys.

3. Build the packages

Jamf installs two packages on each Mac: Beacon’s signed package, and a small package you build that holds the key. Download Beacon’s package and check its checksum and Apple signature:

Download and verify

VERSION="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/asymptote-labs/agent-beacon/releases/latest)"; VERSION="${VERSION##*/v}"
PKG="BeaconEndpointAgent-${VERSION}-arm64.pkg"
BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/v${VERSION}"
curl -fsSLO "${BASE}/${PKG}" && curl -fsSLO "${BASE}/${PKG}.sha256"
test "$(awk '{print $1}' "${PKG}.sha256")" = "$(shasum -a 256 "${PKG}" | awk '{print $1}')" \
  && pkgutil --check-signature "${PKG}"

It’s working when pkgutil prints Status: signed by a developer certificate issued by Apple for distribution. Package the key. The package installs it at /Library/Application Support/Your Organization/Secrets/beacon-gcs-writer.json, owned by root and readable only by root. Replace Your Organization and com.yourorg with your own names, and use the same path in step 5:

Build the key package

install -d -m 0700 beacon-gcs-key
install -m 0600 ./beacon-gcs-writer.json beacon-gcs-key/beacon-gcs-writer.json
pkgbuild --root beacon-gcs-key \
  --install-location "/Library/Application Support/Your Organization/Secrets" \
  --identifier com.yourorg.beacon-gcs-writer-key \
  --version 1 \
  --ownership recommended \
  beacon-gcs-writer-key-1.pkg
rm -rf beacon-gcs-key ./beacon-gcs-writer.json

It’s working when pkgbuild prints Wrote package to beacon-gcs-writer-key-1.pkg. Keep the key out of /opt/beacon and /Library/Application Support/Beacon, because Beacon upgrades and repairs replace those directories. Anyone who can download this package from Jamf can read the key. The key can only add new objects below your prefix. It can’t list, read, change, or delete anything in the bucket.

4. Add them to Jamf Pro

Upload both packages. In Jamf Pro, go to Settings > Computer management > Packages, click New, and upload BeaconEndpointAgent-<version>-arm64.pkg. Do the same for beacon-gcs-writer-key-1.pkg. Add the forwarding script. Go to Settings > Computer management > Scripts, click New, name it Beacon - Forward to GCS, and paste:

Beacon - Forward to GCS

#!/bin/bash
set -euo pipefail

export BEACON_GCS_BUCKET="${4:?Parameter 4 (GCS bucket) is empty}"
export BEACON_GCS_PREFIX="${5:?Parameter 5 (GCS prefix) is empty}"
export GOOGLE_APPLICATION_CREDENTIALS="${6:?Parameter 6 (key file path) is empty}"

# Upload Beacon's agent activity and inventory to the bucket.
/opt/beacon/jamf/claude/gcs/install-forwarder.sh

# Set up Claude Code, Codex, and Cursor for the person logged in now, if anyone is.
/opt/beacon/bin/beacon endpoint user-config repair-installed --system --harness claude,codex,cursor

On the Options tab, label the parameters:

Parameter	Label
4	GCS bucket
5	GCS prefix
6	Key file path

5. Create the policies

Go to Computers > Policies and create two policies. Beacon - Install installs Beacon and the key, starts the forwarder, and sets up the agents for whoever is logged in:

Section	Setting
General	Trigger: Enrollment Complete and Recurring Check-in. Execution Frequency: Once per computer.
Packages	`BeaconEndpointAgent-<version>-arm64.pkg` and `beacon-gcs-writer-key-1.pkg`, both with action Install.
Scripts	`Beacon - Forward to GCS`, priority After. GCS bucket: your bucket. GCS prefix: your prefix, for example `beacon-prod`. Key file path: `/Library/Application Support/Your Organization/Secrets/beacon-gcs-writer.json`.
Scope	One pilot Mac for now.

Beacon - Set up agents at login sets up the agents for each person who logs in later, including on Macs that were at the login window when Beacon installed:

Section	Setting
General	Trigger: Login. Execution Frequency: Ongoing.
Files and Processes	Execute Command: `if [ -x /opt/beacon/bin/beacon ]; then /opt/beacon/bin/beacon endpoint user-config repair-installed --system --harness claude,codex,cursor; fi`
Scope	The same pilot Mac.

Running it at every login is safe. It also puts back Beacon’s settings if an agent update removed them. The Login trigger needs login events turned on in Settings > Computer management > Check-in (Check for policies triggered by login).

6. Confirm on the pilot Mac

Check that the forwarder is running:

sudo launchctl print system/com.beacon.endpoint.gcs-forwarder | grep 'state ='

It should print state = running.

Start a new session in Claude Code and in Codex, and quit and reopen Cursor. Give each one a small task, such as running echo hello in the terminal.

Write a test event:

sudo /opt/beacon/bin/beacon endpoint gcs validate --system

Wait five minutes. Then, on your own Mac, count the events in the bucket by agent:
gcloud storage cat "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/runtime/**" | jq -r '.harness.name' | sort | uniq -c
You should see each agent you used, and test_harness for the test event:
42 claude_code 9 codex_cli 10 cursor 1 test_harness
Inventory arrives as soon as the forwarder starts. gcloud storage ls "gs://${BEACON_GCS_BUCKET}/${BEACON_GCS_PREFIX}/inventory/**" should list at least one object.

These commands use your own Google identity, which needs read access to the bucket, such as Storage Object Viewer. To read as the beacon-endpoint-reader service account instead, give yourself Service Account Token Creator on it and add --impersonate-service-account "$BEACON_GCS_READER_EMAIL" to the command. A new grant can take a few minutes to work.

7. Roll out

Widen the scope of both policies to the Macs you want covered. Each Mac installs Beacon at its next check-in. Ask people to start new agent sessions and to quit and reopen Cursor.

Rotate the writer key

Create a new key as in step 2, and package it as in step 3 with --version 2 and the file name beacon-gcs-writer-key-2.pkg. Keep the same install location.
Upload the new package to Jamf, and swap it for the old one in Beacon - Install so Macs that enroll later get the new key.
Create a policy named Beacon - Rotate GCS key, triggered by Recurring Check-in, Once per computer, and scoped to every Mac with Beacon. Add the new key package and the Beacon - Forward to GCS script with the same parameters as before. The script restarts the forwarder with the new key.

When the policy logs show that every Mac has run it, delete the old key:

gcloud iam service-accounts keys list \
  --project "$GCP_PROJECT" \
  --iam-account "$BEACON_GCS_WRITER_EMAIL" \
  --managed-by user

gcloud iam service-accounts keys delete "<old-key-id>" \
  --project "$GCP_PROJECT" \
  --iam-account "$BEACON_GCS_WRITER_EMAIL"

Add other agents

Beacon supports more agents than these three. To add one, put its name in the --harness list in both the script and the login command, for example claude,codex,cursor,gemini. Agent Harness Integrations lists the agents Beacon supports.

Remove Beacon

Run this as root on each Mac, for example from a Jamf policy script. It removes Beacon’s LaunchDaemons, including the forwarder, /opt/beacon, Beacon’s config and logs, and Beacon’s entries in the Claude Code, Codex, and Cursor settings of every local user, whether or not anyone is logged in. Then it removes the key:

install -m 0700 /opt/beacon/jamf/scripts/full-cleanup.sh /var/tmp/beacon-full-cleanup.sh
BEACON_CLEAN_ALL_USERS=1 /var/tmp/beacon-full-cleanup.sh
rm -f /var/tmp/beacon-full-cleanup.sh
rm -f "/Library/Application Support/Your Organization/Secrets/beacon-gcs-writer.json"
pkgutil --forget com.yourorg.beacon-gcs-writer-key

To delete the bucket and service accounts too, see Remove for Terraform. Deleting the writer service account also deletes its keys.

Troubleshooting

The output of both helpers is in the Jamf policy log. On the Mac, the forwarder’s own log is /Library/Logs/Beacon/com.beacon.endpoint.gcs-forwarder.err:

sudo tail -n 50 /Library/Logs/Beacon/com.beacon.endpoint.gcs-forwarder.err

Google credentials file is not readable, or must be owned by root

The key package didn’t install, or parameter 6 doesn’t match the path it installs to. Check the file:

sudo ls -l "/Library/Application Support/Your Organization/Secrets/beacon-gcs-writer.json"

It should exist with mode -rw------- and owner root.

Invalid JWT Signature

Google rejects a brand-new key for up to a minute, and never accepts a deleted or disabled key. If the key is new, flush the policy’s log so it runs again. Otherwise create a new key and follow Rotate the writer key.

Uploads fail with 403

Check that the bucket and prefix in the policy match your Google Cloud setup exactly, and that the key belongs to beacon-endpoint-writer. The writer can only create objects below <prefix>/. If the bucket uses your own Cloud KMS key, the Cloud Storage service agent needs roles/cloudkms.cryptoKeyEncrypterDecrypter on it.

No events from one agent

Beacon sets up an agent for the person logged in when the script or login policy runs. With that person logged in, run the login command by hand:

sudo /opt/beacon/bin/beacon endpoint user-config repair-installed --system --harness claude,codex,cursor

Then start a new session in the agent, or quit and reopen Cursor. sudo /opt/beacon/bin/beacon endpoint status --system should list telemetry=enabled for Claude Code and Codex CLI.

Activity from before the rollout is missing

The forwarder starts at the end of the activity log, so it uploads only what happens after it starts. It uploads the whole inventory log.

gcloud storage commands fail with the writer's key

That’s expected. The writer can only create objects. Read the bucket with your own identity or the reader service account.

Reference

What the policies put on each Mac:

Path	What it is
`/opt/beacon`	Beacon, its local collector, Vector, and the Jamf helpers
`/var/log/beacon-agent/runtime.jsonl`	Agent activity, uploaded to `<prefix>/runtime/`
`/var/log/beacon-agent/inventory_state.jsonl`	Inventory, uploaded to `<prefix>/inventory/`
`/Library/Application Support/Beacon/Forwarders/gcs-vector.toml`	Forwarder config
`/Library/Application Support/Beacon/Forwarders/gcs-vector.env`	Bucket, prefix, and the key’s path (not the key)
`/Library/LaunchDaemons/com.beacon.endpoint.gcs-forwarder.plist`	The forwarder’s LaunchDaemon
`/Library/Logs/Beacon/com.beacon.endpoint.gcs-forwarder.err`	Forwarder log
Your key path	The writer’s key, readable only by root

Earlier versions of this guide ran /opt/beacon/jamf/claude/gcs/repair-hooks-and-forwarder.sh. Macs set up that way keep forwarding. That helper sets up only Claude Code’s hooks and fails on a Mac where nobody is logged in, so use the script above for new rollouts.

Google Cloud Storage with Terraform

The bucket and service accounts on their own, with every module option.

Jamf Pro

Package deployment, policy scripts, validation, and Extension Attributes.

Object storage forwarding

Forward to S3, Cloud Storage, or both from one Mac.

Event schema

The fields in each uploaded event.

​What you’ll have

​Before you start

​1. Set up Google Cloud

​2. Create the writer key

​3. Build the packages

​4. Add them to Jamf Pro

​5. Create the policies

​6. Confirm on the pilot Mac

​7. Roll out

​Rotate the writer key

​Add other agents

​Remove Beacon

​Troubleshooting

​Reference

​Related