Claude Code Cloud Agents

Overview

Use this integration to capture Claude Code cloud-agent activity and send each session log to one of three places: Asymptote Managed, where it appears in your dashboard next to your laptops’ sessions, or a Google Cloud Storage or Amazon S3 bucket you own. This flow depends on the Beacon CLI. You run beacon cloud commands from your workstation to create a bucket upload path if you want one, print Claude environment variables, and generate the setup script that runs inside the Claude cloud sandbox.

How it works

Claude Code Cloud Agents run in Anthropic’s cloud environment, so Beacon cannot use the long-running endpoint agent that local installs use. Instead, the setup script installs Beacon hooks inside the sandbox. During a cloud-agent session, those hooks write /tmp/beacon/runtime.jsonl. When the agent stops, Beacon ships that file: to Asymptote Managed it posts the new lines to the same ingest endpoint the laptop forwarder uses, so the session shows up in the dashboard a minute or two later; to a bucket it uploads the whole file as one object. The setup has three parts:

Get a device key from Asymptote, or create a GCS or S3 upload path with Beacon.
Add Beacon cloud telemetry environment variables to the Claude Code cloud environment.
Paste a Beacon-generated setup script into the Claude cloud environment.

With Asymptote Managed, the sessions land in the same per-organization tables as your endpoints’ telemetry, attributed to the device you created for the cloud environment. With a bucket, each Claude Code cloud agent session writes one readable JSONL object:

gs://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-claude_code_web-<claude_session_id>.jsonl.gz

or:

s3://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-claude_code_web-<claude_session_id>.jsonl.gz

Prerequisites

Beacon CLI v0.0.51 or later.
For GCS: gcloud installed and authenticated to the Google Cloud project you will use for telemetry storage.
For S3: AWS CLI installed and authenticated to an AWS account where you can create buckets, IAM users, inline IAM policies, and access keys.
Claude Code cloud agent access for the repository you want to test.
A Claude cloud environment with outbound access to:
- For Asymptote Managed: the ingest host from your device key hand-off (currently beacon-ingest-gulcylfs4a-uw.a.run.app)
- For GCS: oauth2.googleapis.com and storage.googleapis.com
- For S3: s3.<region>.amazonaws.com
- github.com
- *.githubusercontent.com

Install or upgrade Beacon before you start:

brew tap asymptote-labs/tap
brew install beacon
brew upgrade beacon
beacon version

For GCS, authenticate gcloud and select your project:

gcloud auth login
gcloud config set project <your-gcp-project>

For S3, authenticate the AWS CLI:

aws sts get-caller-identity

1. Create the upload path

Choose Asymptote Managed, GCS, or S3 for the cloud-agent session logs.

Asymptote Managed

A cloud sandbox has no browser and no Vector, so it cannot run beacon endpoint connect. Instead it authenticates with a device key that an Asymptote operator mints for the environment itself: one key per cloud environment, bound to your organization, listed on /dashboard/endpoints like any laptop and revocable from there. Ask your Asymptote contact for a key, naming the environment (for example “Claude Code web, acme/frontend”). You receive three values to put in the environment in step 2: BEACON_CLOUD_UPLOAD=asymptote, the ingest URL, and the key itself. Self-serve headless enrollment is on the roadmap.

GCS

From your workstation, choose a bucket and prefix:

export GCP_PROJECT="your-gcp-project"
export BEACON_TEST_BUCKET="your-beacon-cloud-agent-traces"
export BEACON_CLOUD_GCS_PREFIX="agent-traces/customer=my-team"

Review the GCP changes Beacon will make:

beacon cloud gcs setup \
  --project "$GCP_PROJECT" \
  --bucket "$BEACON_TEST_BUCKET" \
  --location us-central1 \
  --prefix "$BEACON_CLOUD_GCS_PREFIX" \
  --service-account beacon-cloud-trace-uploader \
  --print

Terminal showing beacon cloud gcs setup --print output with gcloud commands for creating the bucket, service account, and IAM binding. — Review the bucket, service account, and IAM commands before applying them.

Apply the setup and print the Claude environment variables:

beacon cloud gcs setup \
  --project "$GCP_PROJECT" \
  --bucket "$BEACON_TEST_BUCKET" \
  --location us-central1 \
  --prefix "$BEACON_CLOUD_GCS_PREFIX" \
  --service-account beacon-cloud-trace-uploader \
  --apply \
  --print-env

Copy the printed values. Redact BEACON_CLOUD_GCS_CREDENTIALS_B64 anywhere you share screenshots or logs.

Terminal showing beacon cloud gcs setup --apply --print-env output with bucket, prefix, and credentials environment variables. — Copy the printed BEACON_CLOUD_GCS_* variables into the Claude cloud environment.

The helper creates a dedicated uploader service account and grants it object upload access to the selected bucket.

S3

From your workstation, choose a bucket, region, and prefix:

export AWS_REGION="us-east-1"
export BEACON_TEST_BUCKET="your-beacon-cloud-agent-traces"
export BEACON_CLOUD_S3_PREFIX="agent-traces/customer=my-team"

Review the AWS changes Beacon will make:

beacon cloud s3 setup \
  --bucket "$BEACON_TEST_BUCKET" \
  --region "$AWS_REGION" \
  --prefix "$BEACON_CLOUD_S3_PREFIX" \
  --iam-user beacon-cloud-trace-uploader \
  --print

Apply the setup and print the Claude environment variables:

beacon cloud s3 setup \
  --bucket "$BEACON_TEST_BUCKET" \
  --region "$AWS_REGION" \
  --prefix "$BEACON_CLOUD_S3_PREFIX" \
  --iam-user beacon-cloud-trace-uploader \
  --apply \
  --print-env

Copy the printed values. Redact AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY anywhere you share screenshots or logs. The helper creates a dedicated IAM user and grants it s3:PutObject only under the selected bucket prefix.

2. Configure Claude Code Cloud Agents

Open the Claude Code web application and select the cloud environment for your repository.

Claude Code cloud environment selector showing a Beacon Test cloud environment selected. — Select or create the Claude cloud environment that should run Beacon telemetry hooks.

Set network access to Custom and allow:

beacon-ingest-gulcylfs4a-uw.a.run.app
github.com
*.githubusercontent.com

For GCS, allow oauth2.googleapis.com and storage.googleapis.com instead of the ingest host; for S3, allow s3.<region>.amazonaws.com. Add these common environment variables:

BEACON_ORIGIN=cloud
BEACON_RUN_PROVIDER=claude_code_web
BEACON_RUN_EPHEMERAL=true
BEACON_CLOUD_USER_ID_HASH=<stable-user-or-test-id>

For Asymptote Managed, add:

BEACON_CLOUD_UPLOAD=asymptote
BEACON_CLOUD_INGEST_URL=<ingest-url-from-asymptote>
BEACON_CLOUD_DEVICE_KEY=<bcn_device_...-from-asymptote>

For GCS, add:

BEACON_CLOUD_GCS_BUCKET=<bucket-from-setup>
BEACON_CLOUD_GCS_PREFIX=<prefix-from-setup>
BEACON_CLOUD_GCS_CREDENTIALS_B64=<base64-service-account-json>

For S3, add:

BEACON_CLOUD_UPLOAD=s3
BEACON_CLOUD_S3_BUCKET=<bucket-from-setup>
BEACON_CLOUD_S3_PREFIX=<prefix-from-setup>
BEACON_CLOUD_S3_REGION=<region-from-setup>
AWS_ACCESS_KEY_ID=<access-key-id-from-setup>
AWS_SECRET_ACCESS_KEY=<secret-access-key-from-setup>

Claude Code cloud environment settings showing custom network domains, Beacon environment variables, and a setup script. — Configure network access, Beacon metadata, GCS bucket settings, and the setup script in the Claude cloud environment.

3. Add the setup script

Generate the setup script for your Beacon release:

beacon cloud claude-web print-setup --version v0.0.95

Paste the generated script into the Claude environment Setup script field. The script:

installs beacon and beacon-hooks in /tmp/beacon/bin,
finds the cloud sandbox repository root,
writes .claude/settings.local.json inside the sandbox clone,
excludes generated Claude settings from git commits.

If you are testing unreleased Beacon changes from a branch, build beacon and beacon-hooks from that branch in the setup script instead of using print-setup --version.

4. Run a cloud agent task

Start a Claude Code cloud agent task that uses tools. You can start the task from the Claude app on your phone or from the Claude Code web application. For example:

Read the README, run pwd && ls, create a tiny temporary markdown note under /tmp or in the repo, then summarize what you did.

Claude Code cloud agent session showing setup completed, a README task, shell command activity, and a temporary note creation. — A successful Claude Code cloud agent session runs the setup script, starts Claude Code, and produces normal agent activity.

5. Verify upload

For Asymptote Managed, open /dashboard/endpoints: the cloud environment’s device shows a fresh last seen time as soon as the first batch is accepted, and the session appears on /dashboard/telemetry within a couple of minutes, with run.provider=claude_code_web and the Claude session id as the run id. To check the key itself from your workstation:

curl -sS -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $BEACON_CLOUD_DEVICE_KEY" \
  "$BEACON_CLOUD_INGEST_URL/v1/ingest/health"     # 200 valid, 401 revoked

For GCS, list the uploaded session objects:

gcloud storage ls --recursive "gs://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_GCS_PREFIX}/"

For S3, list the uploaded session objects:

aws s3 ls --recursive "s3://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_S3_PREFIX}/"

You should see a path like:

runtime/date=YYYY-MM-DD/<timestamp>-claude_code_web-cse_....jsonl.gz

Google Cloud Storage object browser showing Beacon cloud agent traces partitioned by provider, user ID, Claude run ID, and runtime.jsonl. — Beacon uploads one readable runtime.jsonl object per Claude Code cloud agent session.

Inspect the log:

gcloud storage cat "gs://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_GCS_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" | gzip -dc | head

For S3:

aws s3 cp "s3://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_S3_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" - | gzip -dc | head

Expected fields include:

vendor=beacon
product=endpoint-agent
schema_version=1.0
origin=cloud
harness.name=claude
run.provider=claude_code_web
run.run_id=cse_...

Security note

The Asymptote Managed flow puts a per-device key in the Claude Code environment. It can only append telemetry to your organization’s ingest stream; it reads nothing and grants no dashboard access, and revoking the device on /dashboard/endpoints stops it within a minute. This is the one place a Beacon device key lives in an environment variable: a sandbox has no keychain and no secrets file to hold it, unlike a laptop, where the key stays in a 0600 file. The self-serve GCS flow above creates a dedicated service account scoped to object uploads for one bucket. The S3 flow creates a dedicated IAM user scoped to s3:PutObject under one prefix. All three flows store credentials in the Claude Code environment, so treat those environment variables as sensitive credentials. Claude notes that cloud environment variables are visible to users of that environment and recommends avoiding secrets there when possible. Avoid broad credentials, rotate or delete the generated key after testing, and review access before using this flow with sensitive telemetry.

Troubleshooting

Nothing reaches the dashboard

Run the health check from step 5. A 401 means the key was revoked or the approver left the organization; ask for a new key. A 200 with no sessions usually means the ingest host is not in the environment’s allowed network domains, or the Stop hook did not run (the upload happens on Stop and SessionEnd). Beacon logs upload failures to the hook log with the HTTP status.

The bucket is empty

Confirm the Claude setup script ran and generated hooks:

ls -la .claude
sed -n '1,120p' .claude/settings.local.json

Confirm hooks wrote telemetry:

ls -l /tmp/beacon/runtime.jsonl
head /tmp/beacon/runtime.jsonl

If runtime.jsonl exists but object storage is empty, check network access and credentials. The cloud sandbox must reach either the GCS OAuth/storage endpoints or the regional S3 endpoint you configured.

Claude tries to commit hook settings

The setup script should write .claude/settings.local.json, not .claude/settings.json. settings.local.json is intended for local or sandbox-specific configuration and should stay out of commits.

Claude Code runtime support

Review local Claude Code telemetry through OTLP and hooks.

Log forwarding

Review local endpoint S3 forwarding for persistent endpoint deployments.

Asymptote Managed

Use managed secure ingest for production enterprise cloud-agent telemetry.

Agent Beacon on GitHub

Request new cloud-agent destinations or contribute support.

Get Started

Deploy Asymptote

How Asymptote Works

Manage Asymptote

Agent Harness Integrations

For Security & IT Teams

Support

Contributing

Claude Code Cloud Agents

Overview

How it works

Prerequisites

1. Create the upload path

Asymptote Managed

GCS

S3

2. Configure Claude Code Cloud Agents

3. Add the setup script

4. Run a cloud agent task

5. Verify upload

Security note

Troubleshooting

Nothing reaches the dashboard

The bucket is empty

Claude tries to commit hook settings

Claude Code runtime support

Log forwarding

Asymptote Managed

Agent Beacon on GitHub

​Overview

​How it works

​Prerequisites

​1. Create the upload path

​Asymptote Managed

​GCS

​S3

​2. Configure Claude Code Cloud Agents

​3. Add the setup script

​4. Run a cloud agent task

​5. Verify upload

​Security note

​Troubleshooting

​Nothing reaches the dashboard

​The bucket is empty

​Claude tries to commit hook settings

​Related

Claude Code runtime support

Log forwarding

Asymptote Managed

Agent Beacon on GitHub

Overview

How it works

Prerequisites

1. Create the upload path

Asymptote Managed

GCS

S3

2. Configure Claude Code Cloud Agents

3. Add the setup script

4. Run a cloud agent task

5. Verify upload

Security note

Troubleshooting

Nothing reaches the dashboard

The bucket is empty

Claude tries to commit hook settings

Related