> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asymptotelabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Cloud Agents

> Capture Claude Code cloud agent telemetry and forward cloud-agent runtime logs to customer-managed object storage

<Frame>
  <iframe src="https://www.loom.com/embed/5de72ffb97d7409db292119aada1218b?t=0s" title="Claude Code Cloud Agents walkthrough" allowFullScreen style={{ aspectRatio: "16 / 9", width: "100%", border: 0 }} />
</Frame>

## Integration Overview

Use this integration to capture Claude Code cloud-agent activity and upload each
session log to your own Google Cloud Storage or Amazon S3 bucket. It is meant
for testing cloud-agent telemetry without running a hosted Asymptote backend.

This flow depends on the Beacon CLI. You run `beacon cloud` commands from your
workstation to create the object-storage upload path, print Claude environment
variables, and generate the setup script that runs inside the Claude cloud
sandbox.

<Info>
  If you're interested in leveraging this telemetry ingest across your
  enterprise, [Asymptote Managed](/deployment/managed) is designed for
  production cloud-agent telemetry ingest at scale.
</Info>

## Overview

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`; at the end of the session, Beacon
uploads that file to customer-managed object storage.

```mermaid theme={null}
flowchart LR
  ClaudeWeb["Claude Code Cloud Agents"] --> Hooks["Beacon hooks in sandbox"]
  Hooks --> RuntimeLog["/tmp/beacon/runtime.jsonl"]
  RuntimeLog --> Storage["Customer-managed GCS or S3 bucket"]
```

The setup has three parts:

1. Create a dedicated GCS or S3 upload path with Beacon.
2. Add Beacon cloud telemetry environment variables to the Claude Code cloud environment.
3. Paste a Beacon-generated setup script into the Claude cloud environment.

Each Claude Code cloud agent session writes one readable JSONL object:

```text theme={null}
gs://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-claude_code_web-<claude_session_id>.jsonl.gz
```

or:

```text theme={null}
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 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:

```bash theme={null}
brew tap asymptote-labs/tap
brew install beacon
brew upgrade beacon
beacon version
```

For GCS, authenticate `gcloud` and select your project:

```bash theme={null}
gcloud auth login
gcloud config set project <your-gcp-project>
```

For S3, authenticate the AWS CLI:

```bash theme={null}
aws sts get-caller-identity
```

## 1. Create the Upload Path

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

### GCS

From your workstation, choose a bucket and prefix:

```bash theme={null}
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:

```bash theme={null}
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
```

<Frame caption="Review the bucket, service account, and IAM commands before applying them.">
  <img src="https://mintcdn.com/asymptotelabs/FoBetIyDteoFQFYZ/images/claude-code-on-the-web/beacon-cloud-setup-print.png?fit=max&auto=format&n=FoBetIyDteoFQFYZ&q=85&s=41d9d94327fd0ef98826382cf30a2ffc" width="720" alt="Terminal showing beacon cloud gcs setup --print output with gcloud commands for creating the bucket, service account, and IAM binding." data-path="images/claude-code-on-the-web/beacon-cloud-setup-print.png" />
</Frame>

Apply the setup and print the Claude environment variables:

```bash theme={null}
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.

<Frame caption="Copy the printed BEACON_CLOUD_GCS_* variables into the Claude cloud environment.">
  <img src="https://mintcdn.com/asymptotelabs/FoBetIyDteoFQFYZ/images/claude-code-on-the-web/beacon-cloud-setup-print-env.png?fit=max&auto=format&n=FoBetIyDteoFQFYZ&q=85&s=c49521183e962c5e50bb172f27ac1e5d" alt="Terminal showing beacon cloud gcs setup --apply --print-env output with bucket, prefix, and credentials environment variables." width="529" height="165" data-path="images/claude-code-on-the-web/beacon-cloud-setup-print-env.png" />
</Frame>

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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

<Frame caption="Select or create the Claude cloud environment that should run Beacon telemetry hooks.">
  <img src="https://mintcdn.com/asymptotelabs/FoBetIyDteoFQFYZ/images/claude-code-on-the-web/add-cloud-environment-selector.png?fit=max&auto=format&n=FoBetIyDteoFQFYZ&q=85&s=ad34eb7c13b444f4eae927deede73258" width="720" alt="Claude Code cloud environment selector showing a Beacon Test cloud environment selected." data-path="images/claude-code-on-the-web/add-cloud-environment-selector.png" />
</Frame>

Set network access to **Custom** and allow:

```text theme={null}
s3.<region>.amazonaws.com
github.com
*.githubusercontent.com
```

For GCS, allow `oauth2.googleapis.com` and `storage.googleapis.com` instead of
the S3 regional hostname.

Add these common environment variables:

```bash theme={null}
BEACON_ORIGIN=cloud
BEACON_RUN_PROVIDER=claude_code_web
BEACON_RUN_EPHEMERAL=true
BEACON_CLOUD_USER_ID_HASH=<stable-user-or-test-id>
```

For GCS, add:

```bash theme={null}
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:

```bash theme={null}
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>
```

<Frame caption="Configure network access, Beacon metadata, GCS bucket settings, and the setup script in the Claude cloud environment.">
  <img src="https://mintcdn.com/asymptotelabs/FoBetIyDteoFQFYZ/images/claude-code-on-the-web/claude-env-settings.png?fit=max&auto=format&n=FoBetIyDteoFQFYZ&q=85&s=497d9a65555567841055d4b21e84bd12" alt="Claude Code cloud environment settings showing custom network domains, Beacon environment variables, and a setup script." width="667" height="910" data-path="images/claude-code-on-the-web/claude-env-settings.png" />
</Frame>

## 3. Add the Setup Script

Generate the setup script for your Beacon release:

```bash theme={null}
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.

<Tip>
  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`.
</Tip>

## 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:

```text theme={null}
Read the README, run pwd && ls, create a tiny temporary markdown note under /tmp or in the repo, then summarize what you did.
```

<Frame caption="A successful Claude Code cloud agent session runs the setup script, starts Claude Code, and produces normal agent activity.">
  <img src="https://mintcdn.com/asymptotelabs/FoBetIyDteoFQFYZ/images/claude-code-on-the-web/session-init-and-task-output.png?fit=max&auto=format&n=FoBetIyDteoFQFYZ&q=85&s=87edd40fae953f4a0f3d56a079ab2969" alt="Claude Code cloud agent session showing setup completed, a README task, shell command activity, and a temporary note creation." width="1024" height="589" data-path="images/claude-code-on-the-web/session-init-and-task-output.png" />
</Frame>

## 5. Verify Upload

For GCS, list the uploaded session objects:

```bash theme={null}
gcloud storage ls --recursive "gs://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_GCS_PREFIX}/"
```

For S3, list the uploaded session objects:

```bash theme={null}
aws s3 ls --recursive "s3://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_S3_PREFIX}/"
```

You should see a path like:

```text theme={null}
runtime/date=YYYY-MM-DD/<timestamp>-claude_code_web-cse_....jsonl.gz
```

<Frame caption="Beacon uploads one readable runtime.jsonl object per Claude Code cloud agent session.">
  <img src="https://mintcdn.com/asymptotelabs/FoBetIyDteoFQFYZ/images/claude-code-on-the-web/gcs-object-browser.png?fit=max&auto=format&n=FoBetIyDteoFQFYZ&q=85&s=a07b063e0a09304896875aa69cd909a4" alt="Google Cloud Storage object browser showing Beacon cloud agent traces partitioned by provider, user ID, Claude run ID, and runtime.jsonl." width="1024" height="361" data-path="images/claude-code-on-the-web/gcs-object-browser.png" />
</Frame>

Inspect the log:

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

For S3:

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

Expected fields include:

```text theme={null}
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 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. Both flows store credentials in the Claude
Code environment. This is useful for proof-of-concept testing, but 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

### The bucket is empty

Confirm the Claude setup script ran and generated hooks:

```bash theme={null}
ls -la .claude
sed -n '1,120p' .claude/settings.local.json
```

Confirm hooks wrote telemetry:

```bash theme={null}
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.

## Related

<Columns cols={2}>
  <Card title="Claude Code runtime support" icon="terminal" href="/runtimes/claude-code">
    Review local Claude Code telemetry through OTLP and hooks.
  </Card>

  <Card title="Log forwarding" icon="database" href="/log-forwarding">
    Review local endpoint S3 forwarding for persistent endpoint deployments.
  </Card>

  <Card title="Asymptote Managed" icon="cloud" href="/deployment/managed">
    Use managed secure ingest for production enterprise cloud-agent telemetry.
  </Card>

  <Card title="Agent Beacon on GitHub" icon="github" href="https://github.com/Asymptote-Labs/agent-beacon">
    Request new cloud-agent destinations or contribute support.
  </Card>
</Columns>