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
Add cloud agent telemetry upload support
shukieshahaff045575908
diff --git a/cli/beacon-hooks/cmd/endpoint_events.go b/cli/beacon-hooks/cmd/endpoint_events.goindex 9cac2c67..20d7969c 100644--- a/cli/beacon-hooks/cmd/endpoint_events.go+++ b/cli/beacon-hooks/cmd/endpoint_events.go@@ -1,12 +1,15 @@package cmdimport (+ "context""crypto/sha256""encoding/hex""fmt""path/filepath""strings"+ "time"+ "github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/cloudshuttle""github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/logging")@@ -39,6 +42,15 @@ func emitHookEvent(logger *logging.Logger, action, category, severity, message sif err := logger.EndpointEvent(action, category, severity, message, fields); err != nil {logger.Error("Failed to write endpoint event", "error", err.Error(), "action", action)}+ uploadCloudTelemetry(logger, false)+}++func uploadCloudTelemetry(logger *logging.Logger, force bool) {+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)+ defer cancel()+ if err := cloudshuttle.MaybeUpload(ctx, force); err != nil {+ logger.Warn("Cloud telemetry upload failed", "error", err.Error(), "force", force)+ }}func sessionFields(sessionID string, input map[string]interface{}) map[string]interface{} {diff --git a/cli/beacon-hooks/cmd/session_end.go b/cli/beacon-hooks/cmd/session_end.goindex c17a5e03..53f737ae 100644--- a/cli/beacon-hooks/cmd/session_end.go+++ b/cli/beacon-hooks/cmd/session_end.go@@ -36,6 +36,7 @@ func runSessionEnd(cmd *cobra.Command, args []string) {logger := logging.NewSessionLogger("session-end", platformFlag, sessionID)logger.Info("Session ended", "session_id", sessionID, "platform", platformFlag)emitHookEvent(logger, "session.ended", "session", "info", "Agent session ended", input, sessionFields(sessionID, input))+ uploadCloudTelemetry(logger, true)logFile := config.GetSessionLogFile(platformFlag, sessionID)if err := os.Remove(logFile); err != nil && !os.IsNotExist(err) {@@ -44,6 +45,7 @@ func runSessionEnd(cmd *cobra.Command, args []string) {} else if isDevinLikePlatform(platformFlag) {platformLogger.Info("Session ended", "platform", platformFlag)emitHookEvent(platformLogger, "session.ended", "session", "info", "Agent session ended", input, sessionFields("", input))+ uploadCloudTelemetry(platformLogger, true)}cleaned := state.CleanupStaleForPlatform(platformFlag)diff --git a/cli/beacon-hooks/cmd/stop.go b/cli/beacon-hooks/cmd/stop.goindex 0add11bc..0e555e08 100644--- a/cli/beacon-hooks/cmd/stop.go+++ b/cli/beacon-hooks/cmd/stop.go@@ -50,9 +50,11 @@ func runStop(cmd *cobra.Command, args []string) {if isDevinLikePlatform(platformFlag) {logger.Info("stop completed")emitHookEvent(logger, "tool.completed", "tool", "info", "Agent response completed", input, sessionFields("", input))+ uploadCloudTelemetry(logger, true)outputJSON(emptyResponse)return}+ uploadCloudTelemetry(logger, true)outputJSONAndExit(emptyResponse)return}@@ -74,6 +76,7 @@ func runStop(cmd *cobra.Command, args []string) {elapsed := time.Since(start)logger.Info("stop completed", "duration_ms", elapsed.Milliseconds())emitHookEvent(logger, "tool.completed", "tool", "info", "Agent response completed", input, sessionFields(sessionID, input))+ uploadCloudTelemetry(logger, true)outputJSONAndExit(emptyResponse)}diff --git a/cli/beacon-hooks/internal/cloudshuttle/shuttle.go b/cli/beacon-hooks/internal/cloudshuttle/shuttle.gonew file mode 100644index 00000000..f05e812f--- /dev/null+++ b/cli/beacon-hooks/internal/cloudshuttle/shuttle.go@@ -0,0 +1,429 @@+package cloudshuttle++import (+ "bytes"+ "context"+ "crypto"+ "crypto/rand"+ "crypto/rsa"+ "crypto/sha256"+ "crypto/x509"+ "encoding/base64"+ "encoding/json"+ "encoding/pem"+ "errors"+ "fmt"+ "io"+ "net/http"+ "net/url"+ "os"+ "path"+ "path/filepath"+ "strconv"+ "strings"+ "syscall"+ "time"+)++const (+ defaultInterval = 60 * time.Second+ defaultLogPath = "/tmp/beacon/runtime.jsonl"+ defaultStatePath = "/tmp/beacon/shuttle-state.json"+ defaultTokenURI = "https://oauth2.googleapis.com/token"+ defaultGCSEndpoint = "https://storage.googleapis.com"+ contentTypeJSONL = "application/x-ndjson"+)++var httpClient = http.DefaultClient++type Config struct {+ LogPath string+ StatePath string+ Bucket string+ Prefix string+ CredentialsB64 string+ Interval time.Duration+ Provider string+ RunID string+ UserID string+ Repository string+ GCSEndpoint string+}++type serviceAccount struct {+ ClientEmail string `json:"client_email"`+ PrivateKey string `json:"private_key"`+ TokenURI string `json:"token_uri"`+}++type state struct {+ LastUpload string `json:"last_upload,omitempty"`+ LastSize int64 `json:"last_size,omitempty"`+}++type tokenResponse struct {+ AccessToken string `json:"access_token"`+ TokenType string `json:"token_type"`+ ExpiresIn int `json:"expires_in"`+}++func ConfigFromEnv() Config {+ interval := defaultInterval+ if raw := strings.TrimSpace(os.Getenv("BEACON_CLOUD_UPLOAD_INTERVAL")); raw != "" {+ if raw == "0" {+ interval = 0+ } else if parsed, err := time.ParseDuration(raw); err == nil {+ interval = parsed+ }+ }+ return Config{+ LogPath: firstEnvDefault(defaultLogPath, "BEACON_CLOUD_LOG_PATH", "BEACON_ENDPOINT_LOG", "BEACON_LOG_PATH", "BEACON_RUNTIME_LOG"),+ StatePath: firstEnvDefault(defaultStatePath, "BEACON_CLOUD_SHUTTLE_STATE"),+ Bucket: strings.TrimSpace(os.Getenv("BEACON_CLOUD_GCS_BUCKET")),+ Prefix: strings.Trim(strings.TrimSpace(os.Getenv("BEACON_CLOUD_GCS_PREFIX")), "/"),+ CredentialsB64: strings.TrimSpace(os.Getenv("BEACON_CLOUD_GCS_CREDENTIALS_B64")),+ Interval: interval,+ Provider: firstEnvDefault("claude_code_web", "BEACON_RUN_PROVIDER"),+ RunID: firstEnvDefault(fmt.Sprintf("manual-%d", time.Now().UTC().UnixNano()), "BEACON_RUN_ID", "CLAUDE_CODE_REMOTE_SESSION_ID"),+ UserID: firstEnvDefault("unknown", "BEACON_CLOUD_USER_ID_HASH", "BEACON_CLOUD_USER_ID"),+ Repository: firstEnv("BEACON_RUN_REPOSITORY"),+ GCSEndpoint: firstEnvDefault(defaultGCSEndpoint, "BEACON_CLOUD_GCS_ENDPOINT"),+ }+}++func MaybeUpload(ctx context.Context, force bool) error {+ return Upload(ctx, ConfigFromEnv(), force)+}++func Upload(ctx context.Context, cfg Config, force bool) error {+ if strings.TrimSpace(cfg.Bucket) == "" || strings.TrimSpace(cfg.CredentialsB64) == "" {+ return nil+ }+ if cfg.LogPath == "" {+ cfg.LogPath = defaultLogPath+ }+ if cfg.StatePath == "" {+ cfg.StatePath = defaultStatePath+ }+ if cfg.GCSEndpoint == "" {+ cfg.GCSEndpoint = defaultGCSEndpoint+ }+ info, err := os.Stat(cfg.LogPath)+ if err != nil {+ if os.IsNotExist(err) {+ return nil+ }+ return err+ }+ if info.Size() == 0 {+ return nil+ }+ if !force && !uploadDue(cfg, info.Size(), time.Now().UTC()) {+ return nil+ }+ snapshot, cleanup, err := snapshotLog(cfg.LogPath)+ if err != nil {+ return err+ }+ defer cleanup()+ token, err := accessToken(ctx, cfg.CredentialsB64)+ if err != nil {+ return err+ }+ objectName := ObjectName(cfg)+ if err := uploadObject(ctx, cfg.GCSEndpoint, cfg.Bucket, objectName, snapshot, token); err != nil {+ return err+ }+ return writeState(cfg.StatePath, state{+ LastUpload: time.Now().UTC().Format(time.RFC3339),+ LastSize: info.Size(),+ })+}++func ObjectName(cfg Config) string {+ parts := cleanKeyParts(cfg.Prefix)+ parts = append(parts, "provider="+cleanKeyPart(defaultString(cfg.Provider, "unknown")))+ if cfg.UserID != "" {+ parts = append(parts, "user_id="+cleanKeyPart(cfg.UserID))+ }+ if cfg.Repository != "" {+ parts = append(parts, cleanKeyParts("repo="+cfg.Repository)...)+ }+ parts = append(parts, "run_id="+cleanKeyPart(defaultString(cfg.RunID, "unknown")))+ parts = append(parts, "runtime.jsonl")+ return path.Join(parts...)+}++func uploadDue(cfg Config, currentSize int64, now time.Time) bool {+ if cfg.Interval <= 0 {+ return false+ }+ st, err := readState(cfg.StatePath)+ if err != nil {+ return true+ }+ if currentSize != st.LastSize {+ // Still respect interval to avoid uploading on every hook during active runs.+ }+ if st.LastUpload == "" {+ return true+ }+ last, err := time.Parse(time.RFC3339, st.LastUpload)+ if err != nil {+ return true+ }+ return now.Sub(last) >= cfg.Interval+}++func snapshotLog(logPath string) (string, func(), error) {+ lock, err := os.OpenFile(logPath+".lock", os.O_CREATE|os.O_RDWR, 0644)+ if err != nil {+ return "", func() {}, err+ }+ if err := syscall.Flock(int(lock.Fd()), syscall.LOCK_SH); err != nil {+ _ = lock.Close()+ return "", func() {}, err+ }+ defer syscall.Flock(int(lock.Fd()), syscall.LOCK_UN)+ defer lock.Close()++ source, err := os.Open(logPath)+ if err != nil {+ return "", func() {}, err+ }+ defer source.Close()+ if err := os.MkdirAll(filepath.Dir(logPath), 0755); err != nil {+ return "", func() {}, err+ }+ temp, err := os.CreateTemp(filepath.Dir(logPath), "beacon-cloud-*.jsonl")+ if err != nil {+ return "", func() {}, err+ }+ tempPath := temp.Name()+ cleanup := func() { _ = os.Remove(tempPath) }+ if _, err := io.Copy(temp, source); err != nil {+ _ = temp.Close()+ cleanup()+ return "", func() {}, err+ }+ if err := temp.Close(); err != nil {+ cleanup()+ return "", func() {}, err+ }+ return tempPath, cleanup, nil+}++func accessToken(ctx context.Context, credentialsB64 string) (string, error) {+ decoded, err := base64.StdEncoding.DecodeString(credentialsB64)+ if err != nil {+ return "", fmt.Errorf("decode GCS credentials: %w", err)+ }+ var account serviceAccount+ if err := json.Unmarshal(decoded, &account); err != nil {+ return "", fmt.Errorf("parse GCS credentials: %w", err)+ }+ if account.ClientEmail == "" || account.PrivateKey == "" {+ return "", errors.New("GCS credentials missing client_email or private_key")+ }+ if account.TokenURI == "" {+ account.TokenURI = defaultTokenURI+ }+ assertion, err := signedJWT(account)+ if err != nil {+ return "", err+ }+ form := url.Values{}+ form.Set("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer")+ form.Set("assertion", assertion)+ req, err := http.NewRequestWithContext(ctx, http.MethodPost, account.TokenURI, strings.NewReader(form.Encode()))+ if err != nil {+ return "", err+ }+ req.Header.Set("Content-Type", "application/x-www-form-urlencoded")+ resp, err := httpClient.Do(req)+ if err != nil {+ return "", err+ }+ defer resp.Body.Close()+ body, _ := io.ReadAll(io.LimitReader(resp.Body, 64*1024))+ if resp.StatusCode < 200 || resp.StatusCode >= 300 {+ return "", fmt.Errorf("GCS token exchange failed: %s: %s", resp.Status, strings.TrimSpace(string(body)))+ }+ var token tokenResponse+ if err := json.Unmarshal(body, &token); err != nil {+ return "", fmt.Errorf("parse GCS token response: %w", err)+ }+ if token.AccessToken == "" {+ return "", errors.New("GCS token response missing access_token")+ }+ return token.AccessToken, nil+}++func signedJWT(account serviceAccount) (string, error) {+ now := time.Now().Unix()+ header := map[string]string{"alg": "RS256", "typ": "JWT"}+ claims := map[string]interface{}{+ "iss": account.ClientEmail,+ "scope": "https://www.googleapis.com/auth/devstorage.read_write",+ "aud": account.TokenURI,+ "iat": now,+ "exp": now + 3600,+ }+ encodedHeader, err := encodeJSONSegment(header)+ if err != nil {+ return "", err+ }+ encodedClaims, err := encodeJSONSegment(claims)+ if err != nil {+ return "", err+ }+ signingInput := encodedHeader + "." + encodedClaims+ privateKey, err := parseRSAPrivateKey(account.PrivateKey)+ if err != nil {+ return "", err+ }+ sum := sha256.Sum256([]byte(signingInput))+ signature, err := rsa.SignPKCS1v15(rand.Reader, privateKey, crypto.SHA256, sum[:])+ if err != nil {+ return "", err+ }+ return signingInput + "." + base64.RawURLEncoding.EncodeToString(signature), nil+}++func encodeJSONSegment(value interface{}) (string, error) {+ data, err := json.Marshal(value)+ if err != nil {+ return "", err+ }+ return base64.RawURLEncoding.EncodeToString(data), nil+}++func parseRSAPrivateKey(raw string) (*rsa.PrivateKey, error) {+ block, _ := pem.Decode([]byte(raw))+ if block == nil {+ return nil, errors.New("GCS private key is not PEM encoded")+ }+ if key, err := x509.ParsePKCS8PrivateKey(block.Bytes); err == nil {+ if rsaKey, ok := key.(*rsa.PrivateKey); ok {+ return rsaKey, nil+ }+ return nil, errors.New("GCS private key is not RSA")+ }+ if key, err := x509.ParsePKCS1PrivateKey(block.Bytes); err == nil {+ return key, nil+ }+ return nil, errors.New("parse GCS private key")+}++func uploadObject(ctx context.Context, endpoint, bucket, objectName, filePath, token string) error {+ file, err := os.Open(filePath)+ if err != nil {+ return err+ }+ defer file.Close()+ uploadURL := strings.TrimRight(endpoint, "/") + "/" + escapePath(bucket) + "/" + escapeObjectName(objectName)+ req, err := http.NewRequestWithContext(ctx, http.MethodPut, uploadURL, file)+ if err != nil {+ return err+ }+ if info, err := file.Stat(); err == nil {+ req.ContentLength = info.Size()+ }+ req.Header.Set("Authorization", "Bearer "+token)+ req.Header.Set("Content-Type", contentTypeJSONL)+ resp, err := httpClient.Do(req)+ if err != nil {+ return err+ }+ defer resp.Body.Close()+ body, _ := io.ReadAll(io.LimitReader(resp.Body, 64*1024))+ if resp.StatusCode < 200 || resp.StatusCode >= 300 {+ return fmt.Errorf("GCS upload failed: %s: %s", resp.Status, strings.TrimSpace(string(body)))+ }+ return nil+}++func readState(path string) (state, error) {+ var st state+ data, err := os.ReadFile(path)+ if err != nil {+ return st, err+ }+ err = json.Unmarshal(data, &st)+ return st, err+}++func writeState(path string, st state) error {+ if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {+ return err+ }+ data, err := json.Marshal(st)+ if err != nil {+ return err+ }+ return os.WriteFile(path, data, 0644)+}++func cleanKeyParts(value string) []string {+ var parts []string+ for _, part := range strings.Split(strings.Trim(value, "/"), "/") {+ if cleaned := cleanKeyPart(part); cleaned != "" {+ parts = append(parts, cleaned)+ }+ }+ return parts+}++func cleanKeyPart(value string) string {+ cleaned := strings.TrimSpace(value)+ cleaned = strings.ReplaceAll(cleaned, "\\", "-")+ cleaned = strings.Trim(cleaned, "/")+ if cleaned == "." || cleaned == ".." {+ return ""+ }+ return cleaned+}++func escapeObjectName(objectName string) string {+ parts := strings.Split(objectName, "/")+ for i, part := range parts {+ parts[i] = escapePath(part)+ }+ return strings.Join(parts, "/")+}++func escapePath(value string) string {+ return (&url.URL{Path: value}).EscapedPath()+}++func defaultString(value, fallback string) string {+ if strings.TrimSpace(value) == "" {+ return fallback+ }+ return value+}++func firstEnv(keys ...string) string {+ for _, key := range keys {+ if value := strings.TrimSpace(os.Getenv(key)); value != "" {+ return value+ }+ }+ return ""+}++func firstEnvDefault(defaultValue string, keys ...string) string {+ if value := firstEnv(keys...); value != "" {+ return value+ }+ return defaultValue+}++func EncodeCredentialsForEnv(data []byte) string {+ return base64.StdEncoding.EncodeToString(bytes.TrimSpace(data))+}++func ParseBoolEnv(key string) bool {+ value, _ := strconv.ParseBool(strings.TrimSpace(os.Getenv(key)))+ return value+}diff --git a/cli/beacon-hooks/internal/cloudshuttle/shuttle_test.go b/cli/beacon-hooks/internal/cloudshuttle/shuttle_test.gonew file mode 100644index 00000000..41daf73b--- /dev/null+++ b/cli/beacon-hooks/internal/cloudshuttle/shuttle_test.go@@ -0,0 +1,137 @@+package cloudshuttle++import (+ "context"+ "crypto/rand"+ "crypto/rsa"+ "crypto/x509"+ "encoding/base64"+ "encoding/json"+ "encoding/pem"+ "io"+ "net/http"+ "net/http/httptest"+ "os"+ "path/filepath"+ "strings"+ "testing"+ "time"+)++func TestObjectNamePartitionsByProviderUserRepoAndRun(t *testing.T) {+ got := ObjectName(Config{+ Prefix: "agent-traces/customer=test",+ Provider: "claude_code_web",+ UserID: "user-1",+ Repository: "asymptote-labs/agent-beacon",+ RunID: "cse_123",+ })+ want := "agent-traces/customer=test/provider=claude_code_web/user_id=user-1/repo=asymptote-labs/agent-beacon/run_id=cse_123/runtime.jsonl"+ if got != want {+ t.Fatalf("ObjectName = %q, want %q", got, want)+ }+}++func TestUploadNoopsWithoutCredentials(t *testing.T) {+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ if err := os.WriteFile(logPath, []byte("{}\n"), 0644); err != nil {+ t.Fatalf("write log: %v", err)+ }+ if err := Upload(context.Background(), Config{LogPath: logPath, Bucket: "bucket"}, true); err != nil {+ t.Fatalf("Upload returned error: %v", err)+ }+}++func TestUploadSendsJSONLToGCS(t *testing.T) {+ key := mustRSAKey(t)+ var uploadedPath, uploadedAuth, uploadedType, uploadedBody string+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ switch r.URL.Path {+ case "/token":+ if err := r.ParseForm(); err != nil {+ t.Fatalf("parse form: %v", err)+ }+ if r.Form.Get("grant_type") != "urn:ietf:params:oauth:grant-type:jwt-bearer" || r.Form.Get("assertion") == "" {+ t.Fatalf("unexpected token request: %s", r.Form.Encode())+ }+ _ = json.NewEncoder(w).Encode(map[string]interface{}{"access_token": "test-token", "token_type": "Bearer", "expires_in": 3600})+ default:+ uploadedPath = r.URL.EscapedPath()+ uploadedAuth = r.Header.Get("Authorization")+ uploadedType = r.Header.Get("Content-Type")+ data, _ := io.ReadAll(r.Body)+ uploadedBody = string(data)+ w.WriteHeader(http.StatusOK)+ }+ }))+ defer server.Close()++ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ if err := os.WriteFile(logPath, []byte("{\"event\":\"ok\"}\n"), 0644); err != nil {+ t.Fatalf("write log: %v", err)+ }+ creds := serviceAccount{+ ClientEmail: "[email protected]",+ PrivateKey: pemKey(t, key),+ TokenURI: server.URL + "/token",+ }+ credsJSON, err := json.Marshal(creds)+ if err != nil {+ t.Fatalf("marshal creds: %v", err)+ }+ cfg := Config{+ LogPath: logPath,+ StatePath: filepath.Join(t.TempDir(), "state.json"),+ Bucket: "bucket",+ Prefix: "prefix",+ CredentialsB64: base64.StdEncoding.EncodeToString(credsJSON),+ Provider: "claude_code_web",+ UserID: "user",+ RunID: "run",+ GCSEndpoint: server.URL,+ }+ if err := Upload(context.Background(), cfg, true); err != nil {+ t.Fatalf("Upload returned error: %v", err)+ }+ if uploadedAuth != "Bearer test-token" {+ t.Fatalf("Authorization = %q, want bearer token", uploadedAuth)+ }+ if uploadedType != contentTypeJSONL {+ t.Fatalf("Content-Type = %q, want %q", uploadedType, contentTypeJSONL)+ }+ if !strings.Contains(uploadedPath, "/bucket/prefix/provider=claude_code_web/user_id=user/run_id=run/runtime.jsonl") {+ t.Fatalf("upload path = %q", uploadedPath)+ }+ if uploadedBody != "{\"event\":\"ok\"}\n" {+ t.Fatalf("uploaded body = %q", uploadedBody)+ }+}++func TestUploadRespectsInterval(t *testing.T) {+ dir := t.TempDir()+ statePath := filepath.Join(dir, "state.json")+ if err := writeState(statePath, state{LastUpload: time.Now().UTC().Format(time.RFC3339), LastSize: 10}); err != nil {+ t.Fatalf("write state: %v", err)+ }+ if uploadDue(Config{StatePath: statePath, Interval: time.Hour}, 11, time.Now().UTC()) {+ t.Fatal("uploadDue = true, want false inside interval")+ }+}++func mustRSAKey(t *testing.T) *rsa.PrivateKey {+ t.Helper()+ key, err := rsa.GenerateKey(rand.Reader, 2048)+ if err != nil {+ t.Fatalf("generate key: %v", err)+ }+ return key+}++func pemKey(t *testing.T, key *rsa.PrivateKey) string {+ t.Helper()+ data, err := x509.MarshalPKCS8PrivateKey(key)+ if err != nil {+ t.Fatalf("marshal key: %v", err)+ }+ return string(pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: data}))+}diff --git a/cli/beacon-hooks/internal/logging/endpoint_event_test.go b/cli/beacon-hooks/internal/logging/endpoint_event_test.goindex 861caa29..a5dc3f8d 100644--- a/cli/beacon-hooks/internal/logging/endpoint_event_test.go+++ b/cli/beacon-hooks/internal/logging/endpoint_event_test.go@@ -1,6 +1,7 @@package loggingimport (+ "encoding/json""os""path/filepath""strings"@@ -40,6 +41,44 @@ func TestEndpointEventStillWritesStructuredTelemetry(t *testing.T) {}}+func TestEndpointEventAddsCloudRunMetadataFromEnvironment(t *testing.T) {+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)+ t.Setenv("BEACON_ORIGIN", "cloud")+ t.Setenv("BEACON_RUN_PROVIDER", "claude_code_web")+ t.Setenv("CLAUDE_CODE_REMOTE_SESSION_ID", "cse_123")+ t.Setenv("BEACON_RUN_REPOSITORY", "asymptote-labs/agent-beacon")+ t.Setenv("BEACON_RUN_BRANCH", "main")+ t.Setenv("BEACON_RUN_ACTOR", "[email protected]")+ t.Setenv("BEACON_RUN_EPHEMERAL", "true")+ t.Setenv("BEACON_CLOUD_USER_ID_HASH", "user-hash")++ logger := NewLoggerForPlatform("session-start", "claude")+ if err := logger.EndpointEvent("session.started", "session", "info", "Session started", nil); err != nil {+ t.Fatalf("EndpointEvent returned error: %v", err)+ }++ data, err := os.ReadFile(logPath)+ if err != nil {+ t.Fatalf("read endpoint log: %v", err)+ }+ var event map[string]interface{}+ if err := json.Unmarshal([]byte(strings.TrimSpace(string(data))), &event); err != nil {+ t.Fatalf("unmarshal event: %v", err)+ }+ if got := event["origin"]; got != "cloud" {+ t.Fatalf("origin = %q, want cloud", got)+ }+ run := event["run"].(map[string]interface{})+ if run["provider"] != "claude_code_web" || run["run_id"] != "cse_123" || run["repository"] != "asymptote-labs/agent-beacon" || run["branch"] != "main" || run["actor"] != "[email protected]" || run["ephemeral"] != true {+ t.Fatalf("run metadata = %#v", run)+ }+ user := event["user"].(map[string]interface{})+ if user["uid"] != "user-hash" {+ t.Fatalf("user uid = %q, want user-hash", user["uid"])+ }+}+func TestEndpointEventRotatesRuntimeLog(t *testing.T) {logPath := filepath.Join(t.TempDir(), "runtime.jsonl")if err := os.WriteFile(logPath, []byte("old log contents"), 0644); err != nil {diff --git a/cli/beacon-hooks/internal/logging/logging.go b/cli/beacon-hooks/internal/logging/logging.goindex 869b2e57..d9a37551 100644--- a/cli/beacon-hooks/internal/logging/logging.go+++ b/cli/beacon-hooks/internal/logging/logging.go@@ -118,6 +118,12 @@ func (l *Logger) EndpointEvent(action, category, severity, message string, fieldfunc (l *Logger) baseEndpointEvent(action, category, severity, message string) map[string]interface{} {hostname, _ := os.Hostname()+ user := map[string]interface{}{+ "name": os.Getenv("USER"),+ }+ if uid := firstEnv("BEACON_CLOUD_USER_ID", "BEACON_CLOUD_USER_ID_HASH"); uid != "" {+ user["uid"] = uid+ }event := map[string]interface{}{"timestamp": time.Now().UTC().Format(time.RFC3339),"vendor": "beacon",@@ -133,20 +139,79 @@ func (l *Logger) baseEndpointEvent(action, category, severity, message string) m"hostname": hostname,"os": runtime.GOOS,},- "user": map[string]interface{}{- "name": os.Getenv("USER"),- },+ "user": user,"harness": map[string]interface{}{"name": l.platform,},"message": asymptoteobserve.CleanString(message, asymptoteobserve.DefaultStringLimit, true),}+ if origin := firstEnv("BEACON_ORIGIN"); origin != "" {+ event["origin"] = origin+ }+ if run := cloudRunFields(); len(run) > 0 {+ event["run"] = run+ }if l.sessionID != "" {event["session"] = map[string]interface{}{"id": l.sessionID}}return event}+func cloudRunFields() map[string]interface{} {+ run := map[string]interface{}{}+ if provider := firstEnv("BEACON_RUN_PROVIDER"); provider != "" {+ run["provider"] = provider+ }+ if runID := firstEnv("BEACON_RUN_ID", "CLAUDE_CODE_REMOTE_SESSION_ID"); runID != "" {+ run["run_id"] = runID+ }+ if attempt := firstEnv("BEACON_RUN_ATTEMPT"); attempt != "" {+ run["run_attempt"] = attempt+ }+ if workflow := firstEnv("BEACON_RUN_WORKFLOW"); workflow != "" {+ run["workflow"] = workflow+ }+ if job := firstEnv("BEACON_RUN_JOB"); job != "" {+ run["job"] = job+ }+ if eventName := firstEnv("BEACON_RUN_EVENT_NAME"); eventName != "" {+ run["event_name"] = eventName+ }+ if commit := firstEnv("BEACON_RUN_COMMIT"); commit != "" {+ run["commit"] = commit+ }+ if repository := firstEnv("BEACON_RUN_REPOSITORY"); repository != "" {+ run["repository"] = repository+ }+ if branch := firstEnv("BEACON_RUN_BRANCH"); branch != "" {+ run["branch"] = branch+ }+ if pr := firstEnv("BEACON_RUN_PR"); pr != "" {+ run["pr"] = pr+ }+ if prNumber := firstEnv("BEACON_RUN_PR_NUMBER"); prNumber != "" {+ run["pr_number"] = prNumber+ }+ if actor := firstEnv("BEACON_RUN_ACTOR"); actor != "" {+ run["actor"] = actor+ }+ if ephemeral := firstEnv("BEACON_RUN_EPHEMERAL"); ephemeral != "" {+ if value, err := strconv.ParseBool(ephemeral); err == nil {+ run["ephemeral"] = value+ }+ }+ return run+}++func firstEnv(keys ...string) string {+ for _, key := range keys {+ if value := strings.TrimSpace(os.Getenv(key)); value != "" {+ return value+ }+ }+ return ""+}+func writeEndpointJSON(path string, event map[string]interface{}) error {if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {return errdiff --git a/cli/beacon/.goreleaser.yaml b/cli/beacon/.goreleaser.yamlindex ef68b854..fd649966 100644--- a/cli/beacon/.goreleaser.yaml+++ b/cli/beacon/.goreleaser.yaml@@ -42,11 +42,30 @@ builds:# hooks.bin instead of serving a stale copy from cache.- cmd: bash -c 'cd ../beacon-hooks && GOOS={{ .Os }} GOARCH={{ .Arch }} go build -ldflags "-s -w -X github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/version.Version={{ .Version }}" -o ../beacon/internal/embedded/hooks.bin .'output: true+ - id: beacon-hooks+ main: ../beacon-hooks+ binary: beacon-hooks+ env:+ - CGO_ENABLED=0+ flags:+ - -a+ ldflags:+ - -s -w+ - -X github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/version.Version={{.Version}}+ goos:+ - darwin+ - linux+ goarch:+ - amd64+ - arm64archives:- formats:- tar.gzname_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"+ builds:+ - beacon+ - beacon-hooksfiles:- README*- src: release-collectors/{{ .Os }}_{{ .Arch }}/beacon-otelcol@@ -92,6 +111,7 @@ brews:commit_msg_template: "Homebrew formula update for {{ .ProjectName }} version {{ .Tag }}"install: |bin.install "beacon"+ bin.install "beacon-hooks"bin.install "beacon-otelcol"caveats: |To configure local endpoint telemetry, run:diff --git a/cli/beacon/cmd/cloud.go b/cli/beacon/cmd/cloud.gonew file mode 100644index 00000000..51c71bb6--- /dev/null+++ b/cli/beacon/cmd/cloud.go@@ -0,0 +1,338 @@+package cmd++import (+ "encoding/base64"+ "encoding/json"+ "fmt"+ "os"+ "os/exec"+ "path/filepath"+ "strings"+ "time"++ "github.com/spf13/cobra"+)++var cloudOpts struct {+ binaryPath string+ logPath string+ version string+ project string+ bucket string+ location string+ prefix string+ serviceAccount string+ printOnly bool+ apply bool+ printEnv bool+}++var cloudCmd = &cobra.Command{+ Use: "cloud",+ Short: "Configure Beacon telemetry for provider-managed cloud agents",+}++var cloudClaudeWebCmd = &cobra.Command{+ Use: "claude-web",+ Short: "Generate Claude Code on the web telemetry setup",+}++var cloudClaudeWebPrintHooksCmd = &cobra.Command{+ Use: "print-hooks",+ Short: "Print project-level Claude hook settings for a cloud sandbox",+ SilenceUsage: true,+ RunE: func(cmd *cobra.Command, args []string) error {+ if strings.TrimSpace(cloudOpts.binaryPath) == "" {+ return fmt.Errorf("--binary-path is required")+ }+ if strings.TrimSpace(cloudOpts.logPath) == "" {+ cloudOpts.logPath = "/tmp/beacon/runtime.jsonl"+ }+ fmt.Print(renderClaudeWebHooks(cloudOpts.binaryPath, cloudOpts.logPath))+ return nil+ },+}++var cloudClaudeWebPrintSetupCmd = &cobra.Command{+ Use: "print-setup",+ Short: "Print a Claude Code web environment setup script",+ SilenceUsage: true,+ RunE: func(cmd *cobra.Command, args []string) error {+ if strings.TrimSpace(cloudOpts.version) == "" {+ return fmt.Errorf("--version is required")+ }+ fmt.Print(renderClaudeWebSetup(cloudOpts.version))+ return nil+ },+}++var cloudGCSCmd = &cobra.Command{+ Use: "gcs",+ Short: "Configure GCS forwarding for cloud agent telemetry",+}++var cloudGCSSetupCmd = &cobra.Command{+ Use: "setup",+ Short: "Create or print self-serve GCS setup for cloud agent telemetry",+ SilenceUsage: true,+ RunE: runCloudGCSSetup,+}++func init() {+ rootCmd.AddCommand(cloudCmd)+ cloudCmd.AddCommand(cloudClaudeWebCmd)+ cloudCmd.AddCommand(cloudGCSCmd)+ cloudClaudeWebCmd.AddCommand(cloudClaudeWebPrintHooksCmd)+ cloudClaudeWebCmd.AddCommand(cloudClaudeWebPrintSetupCmd)+ cloudGCSCmd.AddCommand(cloudGCSSetupCmd)++ cloudClaudeWebPrintHooksCmd.Flags().StringVar(&cloudOpts.binaryPath, "binary-path", "", "Path to beacon-hooks inside the cloud sandbox")+ cloudClaudeWebPrintHooksCmd.Flags().StringVar(&cloudOpts.logPath, "log-path", "/tmp/beacon/runtime.jsonl", "Cloud sandbox runtime JSONL path")+ cloudClaudeWebPrintSetupCmd.Flags().StringVar(&cloudOpts.version, "version", "", "Beacon release tag to download, such as v0.0.50")++ cloudGCSSetupCmd.Flags().StringVar(&cloudOpts.project, "project", "", "Google Cloud project ID")+ cloudGCSSetupCmd.Flags().StringVar(&cloudOpts.bucket, "bucket", "", "GCS bucket for cloud agent telemetry")+ cloudGCSSetupCmd.Flags().StringVar(&cloudOpts.location, "location", "us-central1", "GCS bucket location when creating a bucket")+ cloudGCSSetupCmd.Flags().StringVar(&cloudOpts.prefix, "prefix", "agent-traces", "GCS object prefix for cloud telemetry")+ cloudGCSSetupCmd.Flags().StringVar(&cloudOpts.serviceAccount, "service-account", "beacon-cloud-trace-uploader", "Uploader service account ID or email")+ cloudGCSSetupCmd.Flags().BoolVar(&cloudOpts.printOnly, "print", false, "Print the gcloud commands without running them")+ cloudGCSSetupCmd.Flags().BoolVar(&cloudOpts.apply, "apply", false, "Run the gcloud setup commands")+ cloudGCSSetupCmd.Flags().BoolVar(&cloudOpts.printEnv, "print-env", false, "Print Claude web environment variables after setup")+}++func renderClaudeWebHooks(binaryPath, logPath string) string {+ prefix := fmt.Sprintf("BEACON_ENDPOINT_MODE=1 BEACON_ENDPOINT_LOG=%s %s --platform claude", shellQuote(logPath), shellQuote(binaryPath))+ hooks := map[string][]map[string]interface{}{+ "SessionStart": {+ {"hooks": []map[string]interface{}{{"type": "command", "command": prefix + " session-start"}}},+ },+ "UserPromptSubmit": {+ {"hooks": []map[string]interface{}{{"type": "command", "command": prefix + " prompt-submit", "timeout": 30}}},+ },+ "PreToolUse": {+ {"matcher": "Bash|Edit|Write|MultiEdit|Read|Glob|Grep|WebFetch|WebSearch|Agent|mcp__.*", "hooks": []map[string]interface{}{{"type": "command", "command": prefix + " pre-tool"}}},+ },+ "PostToolUse": {+ {"matcher": "*", "hooks": []map[string]interface{}{{"type": "command", "command": prefix + " post-tool"}}},+ },+ "PostToolUseFailure": {+ {"matcher": "*", "hooks": []map[string]interface{}{{"type": "command", "command": prefix + " post-tool"}}},+ },+ "Stop": {+ {"hooks": []map[string]interface{}{{"type": "command", "command": prefix + " stop", "timeout": 45}}},+ },+ "SubagentStart": {+ {"hooks": []map[string]interface{}{{"type": "command", "command": prefix + " subagent-start"}}},+ },+ "SubagentStop": {+ {"hooks": []map[string]interface{}{{"type": "command", "command": prefix + " subagent-stop"}}},+ },+ "PermissionRequest": {+ {"matcher": "*", "hooks": []map[string]interface{}{{"type": "command", "command": prefix + " permission-request"}}},+ },+ "SessionEnd": {+ {"hooks": []map[string]interface{}{{"type": "command", "command": prefix + " session-end"}}},+ },+ }+ out := map[string]interface{}{"hooks": hooks}+ data, _ := json.MarshalIndent(out, "", " ")+ return string(data) + "\n"+}++func renderClaudeWebSetup(version string) string {+ return fmt.Sprintf(`set -euo pipefail+mkdir -p /tmp/beacon/bin /tmp/beacon/logs++BEACON_VERSION=%q+OS="linux"+case "$(uname -m)" in+ x86_64|amd64) ARCH="amd64" ;;+ aarch64|arm64) ARCH="arm64" ;;+ *) echo "unsupported arch $(uname -m)" >&2; exit 1 ;;+esac++ARCHIVE="beacon_${BEACON_VERSION#v}_${OS}_${ARCH}.tar.gz"+BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/${BEACON_VERSION}"+curl -fsSL "${BASE}/${ARCHIVE}" -o "/tmp/beacon/${ARCHIVE}"+tar -xzf "/tmp/beacon/${ARCHIVE}" -C /tmp/beacon/bin+chmod +x /tmp/beacon/bin/beacon /tmp/beacon/bin/beacon-hooks 2>/dev/null || true++mkdir -p .claude+/tmp/beacon/bin/beacon cloud claude-web print-hooks \+ --binary-path /tmp/beacon/bin/beacon-hooks \+ --log-path /tmp/beacon/runtime.jsonl > .claude/settings.json+`, version)+}++func runCloudGCSSetup(cmd *cobra.Command, args []string) error {+ if cloudOpts.project == "" {+ return fmt.Errorf("--project is required")+ }+ if cloudOpts.bucket == "" {+ return fmt.Errorf("--bucket is required")+ }+ if !cloudOpts.apply && !cloudOpts.printOnly {+ return fmt.Errorf("choose --print to review commands or --apply to run them")+ }+ email := serviceAccountEmail(cloudOpts.serviceAccount, cloudOpts.project)+ commands := gcsSetupCommands(cloudOpts.project, cloudOpts.bucket, cloudOpts.location, email, serviceAccountID(cloudOpts.serviceAccount))+ if cloudOpts.printOnly {+ for _, command := range commands {+ fmt.Println(shellCommand(command...))+ }+ }+ if !cloudOpts.apply {+ return nil+ }+ for _, command := range commands {+ if err := runGCloud(command...); err != nil {+ return err+ }+ }+ if cloudOpts.printEnv {+ keyPath, cleanup, err := createServiceAccountKey(cloudOpts.project, email)+ if err != nil {+ return err+ }+ defer cleanup()+ data, err := os.ReadFile(keyPath)+ if err != nil {+ return err+ }+ fmt.Printf("BEACON_CLOUD_GCS_BUCKET=%s\n", cloudOpts.bucket)+ fmt.Printf("BEACON_CLOUD_GCS_PREFIX=%s\n", strings.Trim(cloudOpts.prefix, "/"))+ fmt.Printf("BEACON_CLOUD_GCS_CREDENTIALS_B64=%s\n", base64.StdEncoding.EncodeToString(data))+ }+ return nil+}++func gcsSetupCommands(project, bucket, location, email, accountID string) [][]string {+ return [][]string{+ {"gcloud", "services", "enable", "storage.googleapis.com", "iam.googleapis.com", "--project", project},+ {"gcloud", "storage", "buckets", "describe", "gs://" + bucket, "--project", project},+ {"gcloud", "storage", "buckets", "create", "gs://" + bucket, "--project", project, "--location", location, "--uniform-bucket-level-access"},+ {"gcloud", "iam", "service-accounts", "describe", email, "--project", project},+ {"gcloud", "iam", "service-accounts", "create", accountID, "--project", project, "--display-name", "Beacon cloud trace uploader"},+ {"gcloud", "storage", "buckets", "add-iam-policy-binding", "gs://" + bucket, "--member", "serviceAccount:" + email, "--role", "roles/storage.objectUser"},+ }+}++func runGCloud(args ...string) error {+ // Some setup commands are idempotent checks followed by creates. If a describe+ // succeeds, the matching create may fail with AlreadyExists; ignore only that+ // common case so reruns remain simple for self-serve trials.+ if len(args) >= 5 && args[0] == "gcloud" && args[2] == "buckets" && args[3] == "describe" {+ if err := exec.Command(args[0], args[1:]...).Run(); err == nil {+ return nil+ }+ return nil+ }+ if len(args) >= 5 && args[0] == "gcloud" && args[1] == "iam" && args[2] == "service-accounts" && args[3] == "describe" {+ if err := exec.Command(args[0], args[1:]...).Run(); err == nil {+ return nil+ }+ return nil+ }+ output, err := runGCloudCommand(args...)+ if err != nil {+ text := strings.TrimSpace(string(output))+ if isAlreadyExistsOutput(text) {+ return nil+ }+ if isGCSBucketIAMBinding(args) && serviceAccountNotPropagated(text) {+ var lastOutput []byte+ var lastErr error+ for i := 0; i < 6; i++ {+ time.Sleep(time.Duration(i+1) * 5 * time.Second)+ lastOutput, lastErr = runGCloudCommand(args...)+ if lastErr == nil {+ return nil+ }+ if !serviceAccountNotPropagated(strings.TrimSpace(string(lastOutput))) {+ break+ }+ }+ if lastErr != nil {+ return fmt.Errorf("%s failed after waiting for service account propagation: %w\n%s", shellCommand(args...), lastErr, strings.TrimSpace(string(lastOutput)))+ }+ }+ return fmt.Errorf("%s failed: %w\n%s", shellCommand(args...), err, text)+ }+ return nil+}++func runGCloudCommand(args ...string) ([]byte, error) {+ return exec.Command(args[0], args[1:]...).CombinedOutput()+}++func isAlreadyExistsOutput(text string) bool {+ lower := strings.ToLower(text)+ return strings.Contains(lower, "already exists") ||+ strings.Contains(lower, "already own it") ||+ strings.Contains(lower, "alreadyexists")+}++func isGCSBucketIAMBinding(args []string) bool {+ return len(args) >= 5 &&+ args[0] == "gcloud" &&+ args[1] == "storage" &&+ args[2] == "buckets" &&+ args[3] == "add-iam-policy-binding"+}++func serviceAccountNotPropagated(text string) bool {+ lower := strings.ToLower(text)+ return strings.Contains(lower, "service account") && strings.Contains(lower, "does not exist")+}++func createServiceAccountKey(project, email string) (string, func(), error) {+ dir, err := os.MkdirTemp("", "beacon-cloud-gcs-")+ if err != nil {+ return "", func() {}, err+ }+ cleanup := func() { _ = os.RemoveAll(dir) }+ keyPath := filepath.Join(dir, "uploader.json")+ args := []string{"gcloud", "iam", "service-accounts", "keys", "create", keyPath, "--iam-account", email, "--project", project}+ output, err := exec.Command(args[0], args[1:]...).CombinedOutput()+ if err != nil {+ cleanup()+ return "", func() {}, fmt.Errorf("%s failed: %w\n%s", shellCommand(args...), err, strings.TrimSpace(string(output)))+ }+ return keyPath, cleanup, nil+}++func serviceAccountEmail(value, project string) string {+ value = strings.TrimSpace(value)+ if strings.Contains(value, "@") {+ return value+ }+ return value + "@" + project + ".iam.gserviceaccount.com"+}++func serviceAccountID(value string) string {+ value = strings.TrimSpace(value)+ if before, _, ok := strings.Cut(value, "@"); ok {+ return before+ }+ return value+}++func shellCommand(args ...string) string {+ parts := make([]string, 0, len(args))+ for _, arg := range args {+ parts = append(parts, shellQuote(arg))+ }+ return strings.Join(parts, " ")+}++func shellQuote(value string) string {+ if value == "" {+ return "''"+ }+ if strings.IndexFunc(value, func(r rune) bool {+ return !(r == '-' || r == '_' || r == '.' || r == '/' || r == ':' || r == '@' || r == '=' || r == ',' || (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9'))+ }) == -1 {+ return value+ }+ return "'" + strings.ReplaceAll(value, "'", "'\\''") + "'"+}diff --git a/cli/beacon/cmd/cloud_test.go b/cli/beacon/cmd/cloud_test.gonew file mode 100644index 00000000..adc10f51--- /dev/null+++ b/cli/beacon/cmd/cloud_test.go@@ -0,0 +1,55 @@+package cmd++import (+ "strings"+ "testing"+)++func TestCloudCommandsRegistered(t *testing.T) {+ for _, path := range [][]string{+ {"cloud", "claude-web", "print-hooks"},+ {"cloud", "claude-web", "print-setup"},+ {"cloud", "gcs", "setup"},+ } {+ cmd, _, err := rootCmd.Find(path)+ if err != nil {+ t.Fatalf("Find %v returned error: %v", path, err)+ }+ if cmd == nil || cmd.Use != path[len(path)-1] {+ t.Fatalf("cloud command %v not registered: %#v", path, cmd)+ }+ }+}++func TestRenderClaudeWebHooks(t *testing.T) {+ got := renderClaudeWebHooks("/tmp/beacon/bin/beacon-hooks", "/tmp/beacon/runtime.jsonl")+ for _, want := range []string{+ `"SessionStart"`,+ `"UserPromptSubmit"`,+ `"PreToolUse"`,+ `"PostToolUse"`,+ `"Stop"`,+ `"SessionEnd"`,+ `BEACON_ENDPOINT_MODE=1`,+ `BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl`,+ `/tmp/beacon/bin/beacon-hooks --platform claude`,+ } {+ if !strings.Contains(got, want) {+ t.Fatalf("rendered hooks missing %q:\n%s", want, got)+ }+ }+}++func TestGCSSetupCommands(t *testing.T) {+ commands := gcsSetupCommands("asymptote-code", "bucket", "us-central1", "[email protected]", "uploader")+ got := shellCommand(commands[len(commands)-1]...)+ for _, want := range []string{+ "gcloud storage buckets add-iam-policy-binding gs://bucket",+ "serviceAccount:[email protected]",+ "roles/storage.objectUser",+ } {+ if !strings.Contains(got, want) {+ t.Fatalf("setup command missing %q: %s", want, got)+ }+ }+}diff --git a/examples/cloud-agents/claude-web-gcs.md b/examples/cloud-agents/claude-web-gcs.mdnew file mode 100644index 00000000..04f25190--- /dev/null+++ b/examples/cloud-agents/claude-web-gcs.md@@ -0,0 +1,116 @@+# Claude Code Web to GCS Telemetry++This guide captures Beacon cloud-agent telemetry from Claude Code on the web and+uploads a readable per-run `runtime.jsonl` object to a customer-managed GCS+bucket.++The flow is local-only inside the cloud sandbox until upload time:++1. Claude Code on the web starts a cloud VM and clones the repository.+2. The Claude environment setup script installs Beacon hook tooling into+ `/tmp/beacon/bin`.+3. Project-level `.claude/settings.json` is generated inside the sandbox clone.+4. Hooks write Beacon JSONL to `/tmp/beacon/runtime.jsonl`.+5. Beacon periodically uploads the latest snapshot to GCS.++## 1. Prepare GCS++Run this from a workstation with `gcloud` access to the target project:++```bash+gcloud config set project asymptote-code++export BEACON_TEST_BUCKET="asymptote-beacon-cloud-agent-traces-test"+export BEACON_TEST_LOCATION="us-central1"+export BEACON_CLOUD_GCS_PREFIX="agent-traces/customer=asymptote-test"++beacon cloud gcs setup \+ --project asymptote-code \+ --bucket "${BEACON_TEST_BUCKET}" \+ --location "${BEACON_TEST_LOCATION}" \+ --prefix "${BEACON_CLOUD_GCS_PREFIX}" \+ --service-account beacon-cloud-trace-uploader \++beacon cloud gcs setup \+ --project asymptote-code \+ --bucket "${BEACON_TEST_BUCKET}" \+ --location "${BEACON_TEST_LOCATION}" \+ --prefix "${BEACON_CLOUD_GCS_PREFIX}" \+ --service-account beacon-cloud-trace-uploader \+ --apply \+ --print-env+```++Copy the printed `BEACON_CLOUD_GCS_*` values into the Claude Code web+environment.++## 2. Configure Claude Web++In `claude.ai/code`, edit the target repository's cloud environment.++Set network access so the sandbox can reach `storage.googleapis.com`.++Add environment variables:++```bash+BEACON_ORIGIN=cloud+BEACON_RUN_PROVIDER=claude_code_web+BEACON_RUN_EPHEMERAL=true+BEACON_CLOUD_USER_ID_HASH=<stable-user-or-test-hash>+BEACON_CLOUD_GCS_BUCKET=<bucket>+BEACON_CLOUD_GCS_PREFIX=<prefix>+BEACON_CLOUD_GCS_CREDENTIALS_B64=<base64-service-account-json>+BEACON_CLOUD_UPLOAD_INTERVAL=60s+```++Add this setup script, replacing `vX.Y.Z` with a Beacon release that includes+cloud-agent support:++```bash+set -euo pipefail+mkdir -p /tmp/beacon/bin /tmp/beacon/logs++BEACON_VERSION="vX.Y.Z"+OS="linux"+case "$(uname -m)" in+ x86_64|amd64) ARCH="amd64" ;;+ aarch64|arm64) ARCH="arm64" ;;+ *) echo "unsupported arch $(uname -m)" >&2; exit 1 ;;+esac++ARCHIVE="beacon_${BEACON_VERSION#v}_${OS}_${ARCH}.tar.gz"+BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/${BEACON_VERSION}"+curl -fsSL "${BASE}/${ARCHIVE}" -o "/tmp/beacon/${ARCHIVE}"+tar -xzf "/tmp/beacon/${ARCHIVE}" -C /tmp/beacon/bin+chmod +x /tmp/beacon/bin/beacon /tmp/beacon/bin/beacon-hooks++mkdir -p .claude+/tmp/beacon/bin/beacon cloud claude-web print-hooks \+ --binary-path /tmp/beacon/bin/beacon-hooks \+ --log-path /tmp/beacon/runtime.jsonl > .claude/settings.json+```++The generated `.claude/settings.json` lives only in the cloud sandbox clone+unless the agent explicitly commits it.++## 3. Run and Verify++Start a Claude Code web task that uses tools, for example:++```text+Read the README, run pwd && ls, create a tiny temporary markdown note, then summarize what you did.+```++Verify the uploaded JSONL:++```bash+gcloud storage ls "gs://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_GCS_PREFIX}/provider=claude_code_web/"+gcloud storage cp "gs://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_GCS_PREFIX}/provider=claude_code_web/**/runtime.jsonl" /tmp/beacon-cloud-runtime.jsonl+head -20 /tmp/beacon-cloud-runtime.jsonl+```++Expected fields include `vendor=beacon`, `product=endpoint-agent`,+`schema_version=1.0`, `origin=cloud`, `harness.name=claude`,+`run.provider=claude_code_web`, and a `run.run_id` matching the Claude remote+session ID when available.