Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Capture Cursor Cloud prompts in object storage

shukieshahdddefb1847d1
diff --git a/.cursor/environment.json b/.cursor/environment.json
index 4a7fd055..bb6e73ec 100644
--- a/.cursor/environment.json
+++ b/.cursor/environment.json
@@ -1,5 +1,4 @@
{
- "image": "ubuntu-22.04",
"install": "./.cursor/install.sh",
"start": "./.cursor/start.sh"
}
diff --git a/.cursor/hooks.json b/.cursor/hooks.json
index cd1d310d..3520ec5f 100644
--- a/.cursor/hooks.json
+++ b/.cursor/hooks.json
@@ -3,47 +3,53 @@
"hooks": {
"afterFileEdit": [
{
- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor post-tool"
+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor post-tool"
}
],
"afterShellExecution": [
{
- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor post-tool"
+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor post-tool"
}
],
"beforeReadFile": [
{
- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor pre-tool"
+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor pre-tool"
}
],
"beforeShellExecution": [
{
- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor pre-tool"
+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor pre-tool"
+ }
+ ],
+ "beforeSubmitPrompt": [
+ {
+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor prompt-submit",
+ "timeout": 30
}
],
"postToolUse": [
{
- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor post-tool"
+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor post-tool"
}
],
"postToolUseFailure": [
{
- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor post-tool"
+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor post-tool"
}
],
"preCompact": [
{
- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor cursor-event"
+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor cursor-event"
}
],
"subagentStart": [
{
- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor subagent-start"
+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor subagent-start"
}
],
"subagentStop": [
{
- "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG=/tmp/beacon/runtime.jsonl /tmp/beacon/bin/beacon-hooks --platform cursor subagent-stop"
+ "command": "BEACON_ENDPOINT_MODE=1 BEACON_ORIGIN=cloud BEACON_RUN_PROVIDER=cursor_cloud BEACON_RUN_EPHEMERAL=true BEACON_ENDPOINT_LOG='/tmp/beacon/runtime.jsonl' '/tmp/beacon/bin/beacon-hooks' --platform cursor subagent-stop"
}
]
}
diff --git a/.cursor/install.sh b/.cursor/install.sh
index ae85122c..5991b092 100755
--- a/.cursor/install.sh
+++ b/.cursor/install.sh
@@ -50,8 +50,10 @@ install_go() {
build_from_source() {
install_go
- (cd "$REPO_ROOT/cli/beacon" && go build -o "$BEACON_BIN_DIR/beacon" .)
+ export GOTOOLCHAIN="${GOTOOLCHAIN:-auto}"
(cd "$REPO_ROOT/cli/beacon-hooks" && go build -o "$BEACON_BIN_DIR/beacon-hooks" .)
+ cp "$BEACON_BIN_DIR/beacon-hooks" "$REPO_ROOT/cli/beacon/internal/embedded/hooks.bin"
+ (cd "$REPO_ROOT/cli/beacon" && go build -o "$BEACON_BIN_DIR/beacon" .)
}
if [ -n "${BEACON_VERSION:-}" ]; then
diff --git a/.cursor/start.sh b/.cursor/start.sh
index 0c5a1971..25b9b55a 100755
--- a/.cursor/start.sh
+++ b/.cursor/start.sh
@@ -6,10 +6,26 @@ BEACON_LOG_PATH="${BEACON_CLOUD_LOG_PATH:-$BEACON_HOME/runtime.jsonl}"
mkdir -p "$(dirname "$BEACON_LOG_PATH")"
-if [ -n "${BEACON_CLOUD_GCS_BUCKET:-}" ] && [ -n "${BEACON_CLOUD_GCS_CREDENTIALS_B64:-}" ]; then
- echo "Beacon Cloud GCS forwarding is configured for bucket: $BEACON_CLOUD_GCS_BUCKET"
-else
- echo "Beacon Cloud GCS forwarding is not active; set BEACON_CLOUD_GCS_BUCKET and BEACON_CLOUD_GCS_CREDENTIALS_B64 to enable uploads."
-fi
+case "${BEACON_CLOUD_UPLOAD:-gcs}" in
+ s3)
+ if [ -n "${BEACON_CLOUD_S3_BUCKET:-}" ] &&
+ [ -n "${AWS_ACCESS_KEY_ID:-}" ] &&
+ [ -n "${AWS_SECRET_ACCESS_KEY:-}" ]; then
+ echo "Beacon Cloud S3 forwarding is configured for bucket: $BEACON_CLOUD_S3_BUCKET"
+ else
+ echo "Beacon Cloud S3 forwarding is not active; set the S3 bucket, region, and AWS credentials to enable uploads."
+ fi
+ ;;
+ gcs)
+ if [ -n "${BEACON_CLOUD_GCS_BUCKET:-}" ] && [ -n "${BEACON_CLOUD_GCS_CREDENTIALS_B64:-}" ]; then
+ echo "Beacon Cloud GCS forwarding is configured for bucket: $BEACON_CLOUD_GCS_BUCKET"
+ else
+ echo "Beacon Cloud GCS forwarding is not active; set the GCS bucket and credentials to enable uploads."
+ fi
+ ;;
+ *)
+ echo "Beacon Cloud forwarding has unsupported BEACON_CLOUD_UPLOAD=${BEACON_CLOUD_UPLOAD}."
+ ;;
+esac
echo "Beacon runtime log path: $BEACON_LOG_PATH"
diff --git a/cli/beacon-hooks/cmd/prompt_submit.go b/cli/beacon-hooks/cmd/prompt_submit.go
index b5011db2..18ece901 100644
--- a/cli/beacon-hooks/cmd/prompt_submit.go
+++ b/cli/beacon-hooks/cmd/prompt_submit.go
@@ -54,5 +54,6 @@ func runPromptSubmit(cmd *cobra.Command, args []string) {
}
}
+ maybeUploadCursorCloudTelemetry(logger)
outputJSON(hookNoopResponse())
}
diff --git a/cli/beacon-hooks/cmd/prompt_submit_cloud_test.go b/cli/beacon-hooks/cmd/prompt_submit_cloud_test.go
new file mode 100644
index 00000000..da8d36e6
--- /dev/null
+++ b/cli/beacon-hooks/cmd/prompt_submit_cloud_test.go
@@ -0,0 +1,93 @@
+package cmd
+
+import (
+ "compress/gzip"
+ "encoding/json"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+func TestRunPromptSubmitUploadsCursorCloudTelemetryToS3(t *testing.T) {
+ setupHookConfigDirs(t)
+ platformFlag = "cursor"
+
+ uploaded := make(chan []byte, 1)
+ var uploadPath string
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPut {
+ t.Errorf("method = %s, want PUT", r.Method)
+ }
+ if r.Header.Get("Content-Encoding") != "gzip" {
+ t.Errorf("Content-Encoding = %q, want gzip", r.Header.Get("Content-Encoding"))
+ }
+ if !strings.HasPrefix(r.Header.Get("Authorization"), "AWS4-HMAC-SHA256 ") {
+ t.Errorf("Authorization = %q, want SigV4", r.Header.Get("Authorization"))
+ }
+ uploadPath = r.URL.Path
+ reader, err := gzip.NewReader(r.Body)
+ if err != nil {
+ t.Errorf("open gzip body: %v", err)
+ w.WriteHeader(http.StatusBadRequest)
+ return
+ }
+ defer reader.Close()
+ body, err := io.ReadAll(reader)
+ if err != nil {
+ t.Errorf("read gzip body: %v", err)
+ w.WriteHeader(http.StatusBadRequest)
+ return
+ }
+ uploaded <- body
+ w.WriteHeader(http.StatusOK)
+ }))
+ defer server.Close()
+
+ tempDir := t.TempDir()
+ logPath := filepath.Join(tempDir, "runtime.jsonl")
+ t.Setenv("BEACON_ENDPOINT_LOG", logPath)
+ t.Setenv("BEACON_CLOUD_SHUTTLE_STATE", filepath.Join(tempDir, "shuttle-state.json"))
+ t.Setenv("BEACON_ORIGIN", "cloud")
+ t.Setenv("BEACON_RUN_PROVIDER", "cursor_cloud")
+ t.Setenv("BEACON_RUN_ID", "")
+ t.Setenv("BEACON_CLOUD_UPLOAD", "s3")
+ t.Setenv("BEACON_CLOUD_S3_BUCKET", "telemetry-bucket")
+ t.Setenv("BEACON_CLOUD_S3_PREFIX", "agent-traces")
+ t.Setenv("BEACON_CLOUD_S3_REGION", "us-east-1")
+ t.Setenv("BEACON_CLOUD_S3_ENDPOINT", server.URL)
+ t.Setenv("AWS_ACCESS_KEY_ID", "AKIATEST")
+ t.Setenv("AWS_SECRET_ACCESS_KEY", "test-secret")
+
+ out := runHookWithInput(t, runPromptSubmit, map[string]interface{}{
+ "conversation_id": "conv-prompt",
+ "hook_event_name": "beforeSubmitPrompt",
+ "prompt": "Summarize this repository",
+ "cwd": "/workspace",
+ })
+ if out["continue"] != true {
+ t.Fatalf("prompt response = %#v, want continue=true", out)
+ }
+
+ body := <-uploaded
+ var event map[string]interface{}
+ if err := json.Unmarshal(body, &event); err != nil {
+ t.Fatalf("unmarshal uploaded event: %v\n%s", err, body)
+ }
+ if action := event["event"].(map[string]interface{})["action"]; action != "prompt.submitted" {
+ t.Fatalf("event.action = %q, want prompt.submitted", action)
+ }
+ if prompt := event["prompt"].(map[string]interface{})["text"]; prompt != "Summarize this repository" {
+ t.Fatalf("prompt.text = %q", prompt)
+ }
+ run := event["run"].(map[string]interface{})
+ if run["provider"] != "cursor_cloud" || run["run_id"] != "conv-prompt" {
+ t.Fatalf("run = %#v", run)
+ }
+ if !strings.Contains(uploadPath, "/telemetry-bucket/agent-traces/runtime/") ||
+ !strings.HasSuffix(uploadPath, "-cursor_cloud-conv-prompt.jsonl.gz") {
+ t.Fatalf("upload path = %q", uploadPath)
+ }
+}
diff --git a/cli/beacon/cmd/cloud_test.go b/cli/beacon/cmd/cloud_test.go
index f6a39fbb..e5e99b9b 100644
--- a/cli/beacon/cmd/cloud_test.go
+++ b/cli/beacon/cmd/cloud_test.go
@@ -42,6 +42,8 @@ func TestRenderCursorCloudHooks(t *testing.T) {
`"postToolUseFailure"`,
`"beforeShellExecution"`,
`"afterShellExecution"`,
+ `"beforeSubmitPrompt"`,
+ `prompt-submit`,
`"beforeReadFile"`,
`"afterFileEdit"`,
`"subagentStart"`,
@@ -55,7 +57,7 @@ func TestRenderCursorCloudHooks(t *testing.T) {
t.Fatalf("rendered hooks missing %q:\n%s", want, got)
}
}
- for _, unsupported := range []string{`"preToolUse"`, `"sessionStart"`, `"sessionEnd"`, `"beforeSubmitPrompt"`, `"stop"`} {
+ for _, unsupported := range []string{`"preToolUse"`, `"sessionStart"`, `"sessionEnd"`, `"stop"`} {
if strings.Contains(got, unsupported) {
t.Fatalf("rendered cursor cloud hooks should not contain %q:\n%s", unsupported, got)
}
@@ -72,6 +74,7 @@ func TestRenderCursorCloudSafeHooks(t *testing.T) {
t.Fatalf("render cursor cloud hooks: %v", err)
}
for _, want := range []string{
+ `"beforeSubmitPrompt"`,
`"beforeReadFile"`,
`"postToolUse"`,
`"subagentStart"`,
diff --git a/cli/beacon/internal/endpoint/hooks/cursor.go b/cli/beacon/internal/endpoint/hooks/cursor.go
index f23b20d4..e2b64085 100644
--- a/cli/beacon/internal/endpoint/hooks/cursor.go
+++ b/cli/beacon/internal/endpoint/hooks/cursor.go
@@ -130,6 +130,7 @@ func CursorCloudHookRefs(opts CursorCloudOptions) map[string][]HookRef {
}
prefix := cursorCloudCommandPrefix(opts.BinaryPath, opts.LogPath)
refs := map[string][]HookRef{
+ "beforeSubmitPrompt": {{Command: prefix + " prompt-submit", Timeout: 30}},
"postToolUse": {{Command: prefix + " post-tool"}},
"postToolUseFailure": {{Command: prefix + " post-tool"}},
"beforeReadFile": {
diff --git a/docs/cli/cloud-cursor-print-hooks.mdx b/docs/cli/cloud-cursor-print-hooks.mdx
index ed452cc3..fe72754c 100644
--- a/docs/cli/cloud-cursor-print-hooks.mdx
+++ b/docs/cli/cloud-cursor-print-hooks.mdx
@@ -17,16 +17,17 @@ The rendered hooks set `BEACON_ORIGIN=cloud`, `BEACON_RUN_PROVIDER=cursor_cloud`
Cursor Cloud only runs command-based project hooks after the cloud VM starts.
The generated hook set uses supported Cursor Cloud hooks such as
-`beforeReadFile`, `beforeShellExecution`, `afterShellExecution`,
+`beforeSubmitPrompt`, `beforeReadFile`, `beforeShellExecution`, `afterShellExecution`,
`afterFileEdit`, `postToolUse`, `postToolUseFailure`, `subagentStart`,
-`subagentStop`, and `preCompact`. It does not include broad `preToolUse`,
-`beforeSubmitPrompt`, `sessionStart`, `sessionEnd`, or `stop` because Cursor
-does not run those hooks in cloud agents. See
+`subagentStop`, and `preCompact`. It currently omits broad `preToolUse`,
+`sessionStart`, `sessionEnd`, and `stop`. See
[Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support)
for the current platform support list.
Beacon uses Cursor's `conversation_id` hook payload as the default
`run.run_id` for Cursor Cloud telemetry unless `BEACON_RUN_ID` is already set.
+Prompt events are written and uploaded as soon as `beforeSubmitPrompt` runs,
+including prompt-only follow-up turns.
## Examples
diff --git a/docs/cli/cloud-cursor-print-setup.mdx b/docs/cli/cloud-cursor-print-setup.mdx
index 526dc9e4..68b8d342 100644
--- a/docs/cli/cloud-cursor-print-setup.mdx
+++ b/docs/cli/cloud-cursor-print-setup.mdx
@@ -20,9 +20,11 @@ project hooks with [`beacon cloud cursor print-hooks`](/cli/cloud-cursor-print-h
commit `.cursor/hooks.json` to the repository, then start Cursor Cloud Agents
from a commit that contains that file.
-Cursor cloud agents do not run prompt or session lifecycle hooks such as
-`beforeSubmitPrompt`, `sessionStart`, `sessionEnd`, and `stop`. Beacon refreshes
-the uploaded `runtime.jsonl` object as supported hook events run. See
+Cursor Cloud Agents run the committed `beforeSubmitPrompt` project hook after
+the cloud environment is available, so Beacon can capture and immediately
+upload prompt events. `sessionStart` and `sessionEnd` remain unavailable in
+Cursor Cloud. Beacon refreshes the uploaded `runtime.jsonl` object as supported
+hook events run. See
[Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support)
for the current platform support list.
diff --git a/docs/runtimes/cursor-cloud-agents.mdx b/docs/runtimes/cursor-cloud-agents.mdx
index 3110a7b6..74f37f81 100644
--- a/docs/runtimes/cursor-cloud-agents.mdx
+++ b/docs/runtimes/cursor-cloud-agents.mdx
@@ -1,12 +1,12 @@
---
title: "Cursor Cloud Agents"
-description: "Capture Cursor cloud agent telemetry and forward cloud-agent runtime logs to customer-managed Google Cloud Storage"
+description: "Capture Cursor cloud agent telemetry and forward cloud-agent runtime logs to customer-managed Google Cloud Storage or Amazon S3"
---
## Integration Overview
Use this integration to capture Cursor cloud-agent activity and upload each
-session log to your own Google Cloud Storage bucket. It is meant for testing
+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
@@ -33,12 +33,12 @@ object as supported Cursor hook events run.
flowchart LR
CursorCloud["Cursor Cloud Agents"] --> Hooks["Beacon hooks in sandbox"]
Hooks --> RuntimeLog["/tmp/beacon/runtime.jsonl"]
- RuntimeLog --> GCS["Customer-managed GCS bucket"]
+ RuntimeLog --> Storage["Customer-managed GCS or S3 bucket"]
```
The setup has four parts:
-1. Create a dedicated GCS bucket and uploader service account with Beacon.
+1. Create a dedicated GCS or S3 upload path with Beacon.
2. Add Beacon cloud telemetry environment variables to the Cursor cloud environment.
3. Commit Beacon's project-level Cursor hooks to `.cursor/hooks.json`.
4. Run a Beacon-generated setup script inside the Cursor cloud environment to
@@ -50,6 +50,12 @@ Each Cursor cloud agent conversation writes one readable JSONL object:
gs://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-cursor_cloud-<cursor_conversation_id>.jsonl.gz
```
+or:
+
+```text
+s3://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-cursor_cloud-<cursor_conversation_id>.jsonl.gz
+```
+
Beacon uses Cursor's `conversation_id` hook field as the default `run_id` for
Cursor Cloud telemetry. If you set `BEACON_RUN_ID` yourself, Beacon preserves
that value instead.
@@ -57,14 +63,15 @@ that value instead.
## Prerequisites
- Beacon CLI `v0.0.56` or later.
-- `gcloud` installed and authenticated to the Google Cloud project you will use
- for telemetry storage.
-- A Google Cloud project where you can create buckets, service accounts, IAM
- bindings, and service account keys.
+- For GCS: `gcloud` installed and authenticated to a project where you can
+ create buckets, service accounts, IAM bindings, and service account keys.
+- For S3: AWS CLI installed and authenticated to an account where you can
+ create buckets, IAM users, inline policies, and access keys.
- Cursor Cloud Agent access for the repository you want to test.
- A Cursor cloud environment with outbound access to:
- `oauth2.googleapis.com`
- `storage.googleapis.com`
+ - `s3.<region>.amazonaws.com`
- `github.com`
- `*.githubusercontent.com`
@@ -84,7 +91,11 @@ gcloud auth login
gcloud config set project <your-gcp-project>
```
-## 1. Create the GCS Upload Path
+## 1. Create the Object Storage Upload Path
+
+Choose GCS or S3 for the cloud-agent session logs.
+
+### GCS
From your workstation, choose a bucket and prefix:
@@ -133,6 +144,42 @@ share screenshots or logs.
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
+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
+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 cloud telemetry environment variables:
+
+```bash
+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
+```
+
+The helper creates a dedicated IAM user and grants it `s3:PutObject` only under
+the selected bucket prefix.
+
## 2. Configure Cursor Cloud Agents
Open your Cursor Cloud Agent environment for the repository.
@@ -144,11 +191,27 @@ BEACON_ORIGIN=cloud
BEACON_RUN_PROVIDER=cursor_cloud
BEACON_RUN_EPHEMERAL=true
BEACON_CLOUD_USER_ID_HASH=<stable-user-or-test-id>
+```
+
+For GCS, add:
+
+```bash
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
+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 and Beacon runtime secrets for Cursor Cloud Agents.">
<img src="/images/cursor-cloud-agents/cursor-cloud-agent-config.png" alt="Cursor Cloud Agents settings showing network allowlist entries and Beacon runtime secrets for GCS upload." />
</Frame>
@@ -158,6 +221,7 @@ If your Cursor cloud environment restricts outbound network access, allow:
```text
oauth2.googleapis.com
storage.googleapis.com
+s3.<region>.amazonaws.com
github.com
*.githubusercontent.com
```
@@ -223,22 +287,28 @@ file reads and edits, subagent lifecycle events, and compaction events where
Cursor exposes hook payloads.
<Note>
- Cursor Cloud Agents do not run `beforeSubmitPrompt`, `sessionStart`,
- `sessionEnd`, or `stop` hooks. Prompt text and final session lifecycle hooks
- are therefore not available through this self-serve hook path; Beacon records
- the supported in-sandbox events Cursor exposes after the cloud VM starts. See
+ Beacon captures prompt text through Cursor Cloud's `beforeSubmitPrompt`
+ project hook and uploads that event immediately. Commit `.cursor/hooks.json`
+ before starting the run so the prompt hook is available when the cloud
+ environment starts. `sessionStart` and `sessionEnd` remain unavailable. See
[Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support)
for the current platform support list.
</Note>
-## 6. Verify GCS Upload
+## 6. Verify Object Storage Upload
-List the uploaded session objects:
+For GCS, list the uploaded session objects:
```bash
gcloud storage ls --recursive "gs://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_GCS_PREFIX}/"
```
+For S3:
+
+```bash
+aws s3 ls --recursive "s3://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_S3_PREFIX}/"
+```
+
You should see a path like:
```text
@@ -255,6 +325,12 @@ 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:
+
+```bash
+aws s3 cp "s3://${BEACON_TEST_BUCKET}/${BEACON_CLOUD_S3_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" - | gzip -dc | head
+```
+
Expected fields include:
```text
@@ -268,10 +344,10 @@ run.provider=cursor_cloud
## Security Note
-The self-serve GCS flow above creates a dedicated service account scoped to
-object uploads for one bucket, then stores its credentials in the Cursor cloud
-environment. This is useful for proof-of-concept testing, but treat that
-environment variable as a sensitive credential.
+The self-serve flows create a dedicated GCS service account or AWS IAM user
+scoped to object uploads, then store its credentials in the Cursor cloud
+environment. This is useful for proof-of-concept testing, but treat those
+environment variables as sensitive credentials.
Avoid broad credentials and review access before using this flow with sensitive
telemetry.
@@ -296,15 +372,14 @@ ls -l /tmp/beacon/runtime.jsonl
head /tmp/beacon/runtime.jsonl
```
-If `runtime.jsonl` exists but GCS is empty, check network access and GCS
-credentials. The cloud sandbox must reach both `oauth2.googleapis.com` and
-`storage.googleapis.com`.
+If `runtime.jsonl` exists but object storage is empty, check network access and
+credentials. The cloud sandbox must reach the GCS OAuth/storage endpoints or
+the regional S3 endpoint selected by `BEACON_CLOUD_UPLOAD=s3`.
If `runtime.jsonl` does not exist, confirm the task used a Cursor Cloud
-supported hook surface such as a file read, shell command, file edit, tool use,
-subagent event, or compaction event. Prompt-only tasks do not emit
-`beforeSubmitPrompt` in Cursor Cloud because the prompt is submitted before the
-cloud VM exists. Cursor documents the supported and unsupported cloud hooks in
+supported hook surface such as prompt submission, a file read, shell command,
+file edit, tool use, subagent event, or compaction event. Cursor documents the
+supported and unsupported cloud hooks in
its [Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support).
### Cursor tries to commit hook settings
diff --git a/docs/runtimes/cursor.mdx b/docs/runtimes/cursor.mdx
index cd2fa71f..1292e5a8 100644
--- a/docs/runtimes/cursor.mdx
+++ b/docs/runtimes/cursor.mdx
@@ -47,7 +47,7 @@ beacon endpoint hooks install --harness cursor --level project
| Area | Support |
|------|---------|
-| Prompt telemetry | Supported for local Cursor through `beforeSubmitPrompt` hooks; not available in Cursor Cloud Agents because Cursor submits the prompt before the cloud VM exists. See [Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support). |
+| Prompt telemetry | Supported for local and cloud Cursor through `beforeSubmitPrompt` hooks. Cursor Cloud requires the project hook to be committed before the run starts; Beacon uploads the prompt event immediately. See [Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support). |
| Command, tool, and file telemetry | Supported for tool, shell command, MCP-like, approval, and file edit payloads where Cursor exposes them; Cursor Cloud support is limited to Cursor's [cloud-supported command hooks](https://cursor.com/docs/hooks#cloud-agent-support). |
| Agent reasoning telemetry | Supported for local Cursor through `afterAgentThought` hooks. Each completed thinking block is recorded as an `agent.reasoning` event carrying the reasoning text in the OpenTelemetry GenAI output-messages shape (`gen_ai.output.messages` with a `reasoning` part), plus a `content` marker with the original text's hash and byte count. Reasoning is only available for models/modes where Cursor exposes visible thinking text. |
| Repository and branch context | Events include the workspace path as `repository`, and `branch` is resolved from the workspace's local git checkout (`.git/HEAD`) when Cursor does not supply one; disable local git resolution with `BEACON_DISABLE_GIT_METADATA=1`. |