Skip to content

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

docs(cursor-cloud): set up capture from the install script, with nothing committed

shukieshah94f5a1bc35e5
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index d0b06389..c47e540d 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -87,10 +87,11 @@ For Cursor Cloud Agents, keep the repository-owned setup in `.cursor/`:
```
The install script builds the current branch by default, or downloads a release
-when `BEACON_VERSION` is set. Generate `.cursor/hooks.json` with
-`beacon cloud cursor print-hooks`, then commit it before starting a cloud agent;
-the environment update script must not create hooks after Cursor has already
-loaded the project configuration.
+when `BEACON_VERSION` is set. This repository commits its `.cursor/hooks.json`
+(generated with `beacon cloud cursor print-hooks`) so cloud agents on any branch
+test that branch's hooks. Other repositories don't need to commit anything: the
+install script from `beacon cloud cursor print-setup` writes the hooks at Build
+time and excludes them from git.
For Claude Code on the web, generate the setup script for a Beacon release and
paste it into the provider's cloud setup field:
diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdx
index e485a10e..7e7180a3 100644
--- a/docs/changelog/cli.mdx
+++ b/docs/changelog/cli.mdx
@@ -14,7 +14,9 @@ Stay up to date with the latest changes to the Agent Beacon CLI.
Changes on `main` since v1.3.60. They ship in the next release.
- **Cursor cloud agents no longer leave partial sessions on the endpoint** · While the Cursor desktop app shows a cloud agent, it runs the user-level hooks on your machine for that agent's reasoning and subagent events, but not for its prompts, tool calls, replies or turn ends, which run in Cursor's VM. Beacon recorded those calls as `agent.reasoning` and `subagent.stopped` events from the machine, so a cloud agent looked like a local Cursor session with only reasoning in it, and a subagent's reasoning formed a session of its own. A Cursor hook payload that names a cloud agent (`bc-…`) or one of its subagents (`task-call-…`) and no workspace now writes nothing outside a cloud sandbox. A cloud agent on a self-hosted worker, which runs in a checkout, is still recorded, and so is everything the [Cursor Cloud Agents](/runtimes/cursor-cloud-agents) project hooks capture in the VM.
-- **Cursor cloud agents record reasoning, replies and turn ends** · `beacon cloud cursor print-hooks` now also wires `afterAgentThought`, `afterAgentResponse` and `stop`, which Cursor runs in cloud agents, so a cloud agent's trace carries its reasoning (`agent.reasoning`), its replies (`agent.message`) and the end of each turn (`tool.completed` with `turn.status`), and `stop` uploads the log when the turn is over. Regenerate and commit `.cursor/hooks.json` to pick them up.
+- **Cursor cloud capture needs nothing committed to the repository** · `beacon cloud cursor print-setup` printed a script that installed the binary and told you to commit Beacon's hooks to `.cursor/hooks.json`, and Cursor then ran those committed hooks in every local Cursor session on the repository too. The script now writes the hooks into the checkout itself and lists them in `.git/info/exclude`, so cloud agents never see them as a change to commit. Paste it into the environment's **Install script**: Cursor runs it when it creates a Build, before any agent starts, so the hooks are in place for every agent in the environment. A repository that commits its own `.cursor/hooks.json` is left alone, `print-setup` takes `--safe-hooks`, and only `beacon-hooks` is extracted from the release. See [Cursor Cloud Agents](/runtimes/cursor-cloud-agents).
+- **Cursor cloud agents record reasoning, replies and turn ends** · The cloud hook set now also wires `afterAgentThought`, `afterAgentResponse` and `stop`, which Cursor runs in cloud agents, so a cloud agent's trace carries its reasoning (`agent.reasoning`), its replies (`agent.message`) and the end of each turn (`tool.completed` with `turn.status`), and `stop` uploads the log when the turn is over. Regenerate the install script with `print-setup` to pick them up, or regenerate a committed `.cursor/hooks.json` with `print-hooks`.
+- **A cloud agent's subagents no longer resend its log** · Cursor gives each subagent a conversation id of its own, and the cloud uploader tracked how much it had sent per conversation id. Every switch between an agent and a subagent therefore started over: a bucket got another object holding the whole log, and Beacon Cloud was sent the log again (and dropped the copies by event id). The uploader now tracks one position per sandbox log, so a bucket keeps one object per cloud agent and each line is sent once.
- **Antigravity CLI records every prompt** · Antigravity has no prompt hook, so Beacon recovered only a session's first prompt, from its transcript on the first tool call: later prompts, and turns that ran no tool, were never recorded. The managed hook block now also runs `beacon-hooks` on `PreInvocation`, which Antigravity calls before every model call with the turn's prompt as `lastUserInput`, and Beacon records it on the first call of each turn (`invocationNum` 0), resumed conversations included. Package repair adds the handler to installed user-level hooks; for project-level or manual installs, rerun `beacon endpoint hooks install --harness antigravity` at the same level.
- **Antigravity CLI session sync** · `beacon endpoint antigravity sync|status` (alias `antigravity-cli`) reads the conversations Antigravity keeps under `~/.gemini/antigravity-cli/brain` and records them as `harness.collection_method=poll` events: prompts, agent messages, reasoning, tool calls, commands with exit code and output, file reads and edits, and per-response token usage, with the working directory from `conversation_summaries.db`. The install-time backfill and the scheduled session sync include it, so conversations from before the hooks worked are recorded. For a conversation the hooks already recorded, sync adds only agent messages, reasoning, and token usage from the point the hooks started, plus any prompt the hooks did not record, matched by content hash, such as the later prompts of a conversation recorded by v1.3.60 hooks. `beacon token-usage --coverage` now expects Antigravity usage from the sync instead of reporting it as not instrumented.
- **Antigravity CLI file edits are recorded as edits** · Antigravity edits files with `replace_file_content` and `multi_replace_file_content`, whose names the hook adapter's edit rule did not match, so a live edit was recorded as a plain `tool.invoked`; and its write and replace tools name their file `TargetFile`, which the adapter did not read, so even `write_to_file` carried no path. All three are now `file.modified` with the file's path. The hook adapter and `beacon endpoint antigravity sync` classify Antigravity tools from one table, so a call reads the same on either path.
diff --git a/docs/cli/cloud-cursor-print-hooks.mdx b/docs/cli/cloud-cursor-print-hooks.mdx
index 94503a30..94a20536 100644
--- a/docs/cli/cloud-cursor-print-hooks.mdx
+++ b/docs/cli/cloud-cursor-print-hooks.mdx
@@ -6,8 +6,12 @@ description: "Print Cursor cloud hook settings"
## Command overview
`beacon cloud cursor print-hooks` prints project-level Cursor hook settings for
-a cloud sandbox. Commit the rendered JSON to `.cursor/hooks.json` before
-starting Cursor Cloud Agents.
+a cloud sandbox. The install script from
+[`beacon cloud cursor print-setup`](/cli/cloud-cursor-print-setup) already
+writes these hooks at Build time without committing them. Use `print-hooks`
+when you want the hooks committed to `.cursor/hooks.json` instead, or to merge
+Beacon's entries into a hooks file the repository already commits. Committed
+project hooks also run in every local Cursor session on the repository.
```bash title="Command syntax"
beacon cloud cursor print-hooks
@@ -19,7 +23,6 @@ The rendered hooks set `BEACON_ORIGIN=cloud`, `BEACON_RUN_PROVIDER=cursor_cloud`
`--log-path` defaults to `/tmp/beacon/runtime.jsonl` and must name a file under `/tmp/beacon`, the only directory the cloud shuttle uploads from; any other path is rejected.
-Cursor Cloud only runs command-based project hooks after the cloud VM starts.
The generated hook set uses supported Cursor Cloud hooks such as
`beforeSubmitPrompt`, `beforeReadFile`, `beforeShellExecution`, `afterShellExecution`,
`afterFileEdit`, `postToolUse`, `postToolUseFailure`, `subagentStart`,
diff --git a/docs/cli/cloud-cursor-print-setup.mdx b/docs/cli/cloud-cursor-print-setup.mdx
index 120d6304..201f2c52 100644
--- a/docs/cli/cloud-cursor-print-setup.mdx
+++ b/docs/cli/cloud-cursor-print-setup.mdx
@@ -1,46 +1,46 @@
---
title: "beacon cloud cursor print-setup"
-description: "Print a Cursor cloud agent binary setup script"
+description: "Print a Cursor cloud environment install script that installs Beacon and its hooks"
---
## Command overview
-`beacon cloud cursor print-setup` prints a Cursor cloud agent setup script for
-installing Beacon binaries in the cloud sandbox.
+`beacon cloud cursor print-setup` prints the install script for a Cursor cloud
+agent environment. Paste it into the environment's **Install script** field.
```bash title="Command syntax"
-beacon cloud cursor print-setup
+beacon cloud cursor print-setup --version vX.Y.Z
```
-Paste the generated script into the Cursor cloud environment setup step. It
-installs `beacon` and `beacon-hooks` into `/tmp/beacon/bin`.
+Cursor runs the install script when it creates a Build, before any agent
+starts. The script:
+
+- downloads `beacon-hooks` from the release you name into `/tmp/beacon/bin`,
+- writes Beacon's project hooks to `.cursor/hooks.json` in the checkout, with
+ the hook set [`beacon cloud cursor print-hooks`](/cli/cloud-cursor-print-hooks)
+ prints,
+- lists `.cursor/hooks.json` in `.git/info/exclude`, so agents never see it as a
+ change to commit,
+- leaves the repository alone if it commits its own `.cursor/hooks.json`.
-The generated script does not write or merge `.cursor/hooks.json`. Generate
-project hooks with [`beacon cloud cursor print-hooks`](/cli/cloud-cursor-print-hooks),
-commit `.cursor/hooks.json` to the repository, then start Cursor Cloud Agents
-from a commit that contains that file.
+The Build keeps the binary and the hooks, so every agent in the environment
+starts with them. Nothing is committed, and the hooks never run in local Cursor
+sessions. An agent started before the environment's first Build runs without
+them and is not recorded.
-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.
+`--safe-hooks` leaves out the shell and edit hooks (`beforeShellExecution`,
+`afterShellExecution`, `afterFileEdit`), so you can prove the upload works
+before the agent's commands and edits pass through Beacon.
## Examples
-Print setup for a specific Beacon release:
+Print the install script for a specific Beacon release:
-```bash title="Print setup for a specific Beacon release"
+```bash title="Print the install script for a specific Beacon release"
beacon cloud cursor print-setup --version vX.Y.Z
```
-Replace `vX.Y.Z` with the desired release tag. Cursor Cloud prompt capture
-requires a release containing the committed `beforeSubmitPrompt` hook and
-immediate upload behavior. Until that release exists, build the branch
-containing the change in the cloud environment instead of downloading an older
-release.
+Replace `vX.Y.Z` with the latest Beacon release tag.
## Related
@@ -49,9 +49,9 @@ release.
Review cloud command group behavior.
</Card>
<Card title="beacon cloud cursor print-hooks" icon="plug" href="/cli/cloud-cursor-print-hooks">
- Print project-level Cursor hook settings for a cloud sandbox.
+ Print the project hooks, to commit them yourself.
</Card>
<Card title="Cursor Cloud Agents" icon="cloud" href="/runtimes/cursor-cloud-agents">
- Configure Cursor cloud agent telemetry and GCS or S3 upload end to end.
+ Configure Cursor cloud agent telemetry end to end.
</Card>
</Columns>
diff --git a/docs/cli/cloud.mdx b/docs/cli/cloud.mdx
index 8bf2399f..af28c232 100644
--- a/docs/cli/cloud.mdx
+++ b/docs/cli/cloud.mdx
@@ -30,10 +30,10 @@ and [Cursor Cloud Agents](/runtimes/cursor-cloud-agents).
Print Claude hook settings for a cloud sandbox.
</Card>
<Card title="beacon cloud cursor print-setup" icon="cloud" href="/cli/cloud-cursor-print-setup">
- Print a Cursor cloud agent binary setup script.
+ Print a Cursor cloud environment install script that installs Beacon and its hooks.
</Card>
<Card title="beacon cloud cursor print-hooks" icon="plug" href="/cli/cloud-cursor-print-hooks">
- Print Cursor project hook settings to commit for cloud agents.
+ Print Cursor project hook settings for cloud agents, to commit or merge yourself.
</Card>
<Card title="beacon cloud gcs setup" icon="database" href="/cli/cloud-gcs-setup">
Create or print self-serve GCS setup commands for cloud-agent telemetry.
diff --git a/docs/cli/index.mdx b/docs/cli/index.mdx
index 5c3475ad..b14119ec 100644
--- a/docs/cli/index.mdx
+++ b/docs/cli/index.mdx
@@ -121,8 +121,8 @@ Configure provider-managed cloud agent telemetry setup helpers.
|---------|-------------|
| [`beacon cloud claude-web print-setup`](/cli/cloud-claude-web-print-setup) | Print a Claude Code cloud environment setup script. |
| [`beacon cloud claude-web print-hooks`](/cli/cloud-claude-web-print-hooks) | Print Claude hook settings for a cloud sandbox. |
-| [`beacon cloud cursor print-setup`](/cli/cloud-cursor-print-setup) | Print a Cursor cloud agent binary setup script. |
-| [`beacon cloud cursor print-hooks`](/cli/cloud-cursor-print-hooks) | Print Cursor project hook settings to commit for cloud agents. |
+| [`beacon cloud cursor print-setup`](/cli/cloud-cursor-print-setup) | Print a Cursor cloud environment install script that installs Beacon and its hooks. |
+| [`beacon cloud cursor print-hooks`](/cli/cloud-cursor-print-hooks) | Print Cursor project hook settings for cloud agents, to commit or merge yourself. |
| [`beacon cloud gcs setup`](/cli/cloud-gcs-setup) | Create or print GCS setup commands for cloud-agent telemetry. |
| [`beacon cloud s3 setup`](/cli/cloud-s3-setup) | Create or print S3 setup commands for cloud-agent telemetry. |
diff --git a/docs/runtimes/cursor-cloud-agents.mdx b/docs/runtimes/cursor-cloud-agents.mdx
index 45fcf064..df71bc8a 100644
--- a/docs/runtimes/cursor-cloud-agents.mdx
+++ b/docs/runtimes/cursor-cloud-agents.mdx
@@ -1,50 +1,54 @@
---
title: "Cursor Cloud Agents"
-description: "Capture Cursor cloud agent telemetry and forward cloud-agent runtime logs to customer-managed Google Cloud Storage or Amazon S3"
+description: "Capture Cursor cloud agent telemetry and send each session log to object storage you own or to Beacon Cloud, with nothing committed to your repository"
---
## Overview
-Use this integration to capture Cursor 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 Beacon backend.
+Use this integration to capture what Cursor cloud agents do and send each
+session log to a Google Cloud Storage or Amazon S3 bucket you own, or to
+[Beacon Cloud](/deployment/managed). Nothing is committed to your repository,
+and nothing changes for developers who use Cursor on their own machines.
This flow depends on the Beacon CLI. You run `beacon cloud` commands from your
-workstation to create the object-storage upload path, generate project hooks to
-commit to your repository, and generate the setup script that installs Beacon
-binaries in the Cursor cloud sandbox.
-
-<Info>
- If you're interested in leveraging this telemetry ingest across your
- enterprise, [Beacon Cloud](/deployment/managed) is designed for
- production cloud-agent telemetry ingest at scale.
-</Info>
+workstation to create a bucket upload path and to generate the install script
+that sets up Beacon inside each Cursor cloud environment.
## How it works
-Cursor Cloud Agents run in Cursor's cloud environment, so Beacon cannot use the
-long-running endpoint agent that local installs use. Instead, commit
-project-level Cursor hooks to `.cursor/hooks.json` and use the setup script to
-install Beacon binaries in the sandbox. During a cloud-agent session, those
-hooks write `/tmp/beacon/runtime.jsonl`; Beacon refreshes the corresponding GCS
-or S3 object as supported Cursor hook events run.
+Cursor cloud agents run in VMs that Cursor manages, so Beacon cannot use the
+long-running endpoint agent that local installs use. Beacon runs inside the VM
+instead:
+
+1. Each Cursor environment has an install script. Cursor runs it when it
+ creates a Build, the prepared VM that every agent in the environment starts
+ from.
+2. Beacon's install script, from `beacon cloud cursor print-setup`, downloads
+ `beacon-hooks` to `/tmp/beacon/bin` and writes Beacon's hooks to
+ `.cursor/hooks.json` in the checkout. It lists that file in
+ `.git/info/exclude`, so agents never see it as a change to commit.
+3. The Build keeps both, so every agent starts with Beacon's hooks in place.
+ During a session the hooks write `/tmp/beacon/runtime.jsonl` and upload it
+ as they run: to a bucket as one object per agent, rewritten as the session
+ grows, or to Beacon Cloud as new lines.
```mermaid
flowchart LR
- CursorCloud["Cursor Cloud Agents"] --> Hooks["Beacon hooks in sandbox"]
+ Install["Install script, run at Build"] --> Hooks["Beacon hooks in the VM"]
+ CursorCloud["Cursor cloud agent"] --> Hooks
Hooks --> RuntimeLog["/tmp/beacon/runtime.jsonl"]
- RuntimeLog --> Storage["Customer-managed GCS or S3 bucket"]
+ RuntimeLog --> Storage["Your GCS or S3 bucket"]
+ RuntimeLog --> Managed["Beacon Cloud"]
```
The setup has four parts:
-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
- install `/tmp/beacon/bin/beacon` and `/tmp/beacon/bin/beacon-hooks`.
+1. Create a GCS or S3 upload path with Beacon, or get a device key for Beacon Cloud.
+2. Add Beacon's upload settings to Cursor as secrets.
+3. Create a Cursor environment with Beacon's install script and let its first Build finish.
+4. Run a cloud agent and check the session log.
-Each Cursor cloud agent conversation writes one readable JSONL object:
+With a bucket, each Cursor cloud agent writes one readable JSONL object:
```text
gs://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<timestamp>-cursor_cloud-<cursor_conversation_id>.jsonl.gz
@@ -56,9 +60,10 @@ or:
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.
+The object is named after the conversation that uploaded first, normally the
+agent's. 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.
### Cloud agents started from Cursor desktop
@@ -77,20 +82,20 @@ you read older endpoint data.
## Prerequisites
-- A current Beacon CLI release. Releases after `v1.3.60` also record the
- agent's reasoning, its replies, and the end of each turn.
+- The latest Beacon CLI on your workstation.
- 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.
- `jq` on the verification workstation.
-- Cursor Cloud Agent access for the repository you want to test.
+- Cursor cloud agent access for the repository, and permission to create a
+ cloud agent environment for it.
- A Cursor cloud environment with outbound access to:
- - `oauth2.googleapis.com`
- - `storage.googleapis.com`
- - `s3.<region>.amazonaws.com`
- - `github.com`
- - `*.githubusercontent.com`
+ - For Beacon Cloud: the ingest host from your device key hand-off
+ - For GCS: `oauth2.googleapis.com` and `storage.googleapis.com`
+ - For S3: `s3.<region>.amazonaws.com`
+ - `github.com` and `*.githubusercontent.com`, where the install script
+ downloads Beacon
Install or upgrade Beacon before you start:
@@ -103,16 +108,26 @@ brew upgrade beacon
beacon version
```
-Authenticate `gcloud` and select your project:
+For GCS, authenticate `gcloud` and select your project:
```bash
gcloud auth login
gcloud config set project <your-gcp-project>
```
-## 1. Create the object storage upload path
+## 1. Choose where session logs go
+
+Send session logs to a bucket you own (GCS or S3) or to Beacon Cloud.
+
+### Beacon Cloud
-Choose GCS or S3 for the cloud-agent session logs.
+To send Cursor cloud sessions to [Beacon Cloud](/deployment/managed), where they
+appear next to your endpoints' sessions, [contact us](https://asymptotelabs.ai/contact)
+for a device key. A cloud VM has no browser, so it cannot run
+[`beacon endpoint connect`](/cli/endpoint-connect). The key is minted for the
+environment and bound to your organization, and it is listed under **Devices**
+on the dashboard like any laptop and revocable from there. You receive three
+values for step 2: `BEACON_CLOUD_UPLOAD=asymptote`, the ingest URL, and the key.
### GCS
@@ -203,17 +218,19 @@ the selected bucket prefix.
Copy the printed values. Treat `AWS_ACCESS_KEY_ID` and
`AWS_SECRET_ACCESS_KEY` as sensitive and redact them from screenshots and logs.
-## 2. Configure Cursor Cloud Agents
+## 2. Add the upload settings to Cursor
-Open your Cursor Cloud Agent environment for the repository.
+In [cursor.com/dashboard/cloud-agents](https://cursor.com/dashboard/cloud-agents),
+open **Secrets** and add the values for your destination. User secrets reach
+every cloud agent you start, and team secrets reach your team's. Cursor gives
+secrets only to agents started after you add them.
-Add these environment variables:
+For Beacon Cloud, add:
```bash
-BEACON_ORIGIN=cloud
-BEACON_RUN_PROVIDER=cursor_cloud
-BEACON_RUN_EPHEMERAL=true
-BEACON_CLOUD_USER_ID_HASH=<stable-user-or-test-id>
+BEACON_CLOUD_UPLOAD=asymptote
+BEACON_CLOUD_INGEST_URL=<ingest-url-from-your-hand-off>
+BEACON_CLOUD_DEVICE_KEY=<device-key-from-your-hand-off>
```
For GCS, add:
@@ -235,86 +252,62 @@ 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 object-storage upload." />
-</Frame>
-
-If your Cursor cloud environment restricts outbound network access, allow:
+Optionally, set `BEACON_CLOUD_USER_ID_HASH` to a stable id for the person or
+test; Beacon records it as `user.uid`. Beacon's hooks set `BEACON_ORIGIN=cloud`,
+`BEACON_RUN_PROVIDER=cursor_cloud`, and `BEACON_RUN_EPHEMERAL=true` themselves.
-```text
-oauth2.googleapis.com
-storage.googleapis.com
-s3.<region>.amazonaws.com
-github.com
-*.githubusercontent.com
-```
+If your Cursor environment restricts outbound network access, allow the hosts
+listed under [Prerequisites](#prerequisites).
-## 3. Commit Cursor project hooks
+## 3. Create the Cursor environment
-Cursor Cloud Agents load project hooks from `.cursor/hooks.json` at repository
-checkout and task start. Generate the hook file locally, commit it, and push it
-before starting cloud agents:
+Generate the install script for the latest Beacon release:
```bash
-mkdir -p .cursor
-beacon cloud cursor print-hooks \
- --binary-path /tmp/beacon/bin/beacon-hooks \
- --log-path /tmp/beacon/runtime.jsonl > .cursor/hooks.json
-git add .cursor/hooks.json
-git commit -m "Add Beacon Cursor Cloud hooks"
-git push
+beacon cloud cursor print-setup --version vX.Y.Z
```
-<Warning>
- Do not rely on generating `.cursor/hooks.json` from inside the Cursor Cloud
- setup script. Cursor Cloud may load project hooks before the setup script
- creates files in the VM. Committing `.cursor/hooks.json` makes the hook config
- available when the agent starts.
-</Warning>
+Replace `vX.Y.Z` with the latest Beacon release tag. The script:
-## 4. Add the setup script
+- downloads `beacon-hooks` to `/tmp/beacon/bin`,
+- writes Beacon's hooks to `.cursor/hooks.json` in the checkout and lists that
+ file in `.git/info/exclude`,
+- leaves the repository's own `.cursor/hooks.json` alone if it commits one.
-Generate the setup script for your Beacon release:
+Then create the environment:
-```bash
-beacon cloud cursor print-setup --version vX.Y.Z
-```
-
-Replace `vX.Y.Z` with the latest Beacon release tag.
+1. In [cursor.com/dashboard/cloud-agents](https://cursor.com/dashboard/cloud-agents),
+ open **Environments** and create one for your repository.
+2. Paste the script into **Install script**.
+3. Wait for the first Build to finish on the environment's **Builds** tab. A
+ successful Build's log ends with `Beacon wrote <repository>/.cursor/hooks.json`.
-Paste the generated script into the Cursor cloud environment setup step. The
-script:
-
-- installs `beacon` and `beacon-hooks` in `/tmp/beacon/bin`,
-- does not modify `.cursor/hooks.json`,
-- expects project hooks to already be committed in the repository.
+<Warning>
+ An agent started before the environment's first Build runs on Cursor's
+ default image, where the install script has not run, so Beacon records nothing
+ for it. Start agents once the first Build has finished.
+</Warning>
-<Frame caption="Paste the generated Beacon setup script into the Cursor cloud environment update script.">
- <img src="/images/cursor-cloud-agents/cursor-environment-script.png" alt="Cursor cloud environment configuration showing a Beacon setup script in the update script field and Beacon runtime secrets below it." />
-</Frame>
+If your repository commits a `.cursor/environment.json`, Cursor takes the
+install script from that file and the dashboard field is read-only. Save the
+script in the repository, for example as `.cursor/beacon-install.sh`, and run it
+from the file's `install` command. The hooks are still written at Build time and
+stay out of the repository.
-<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>
+`--safe-hooks` leaves out the shell and edit hooks (`beforeShellExecution`,
+`afterShellExecution`, `afterFileEdit`), so you can prove the upload works before
+the agent's commands and edits pass through Beacon.
-## 5. Run a cloud agent task
+## 4. Run a cloud agent task
-Start a Cursor cloud agent task that uses tools so the environment becomes
-writable and project hooks become active. For example:
+Start a cloud agent in the environment with a task that uses tools. For example:
```text
Read the README, run pwd && ls, create a tiny temporary markdown note under
-/tmp or in the repo, then summarize what you did.
+/tmp, then summarize what you did.
```
-Beacon captures observed prompt submissions, tool use, shell execution, file
-reads and edits, subagent lifecycle events, compaction events, the agent's
-reasoning and replies, and the end of each turn where Cursor exposes hook
-payloads.
-
-Then submit a prompt-only follow-up with a unique marker:
+Then send a prompt-only follow-up with a unique marker:
```text
BEACON_PROMPT_SMOKE_<unique-id>
@@ -323,18 +316,14 @@ Do not inspect files or run tools. Reply exactly: PROMPT CAPTURE TEST COMPLETE
```
<Note>
- 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. Cursor can perform early read-only or bootstrap work
- before project hooks become active, so the initial launch prompt may be
- absent; follow-up prompts are captured once hooks are running.
- `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.
+ Cursor runs fewer hooks in an agent's first turn, so the launch prompt is not
+ recorded. The follow-up prompt is. See [What Beacon records](#what-beacon-records).
</Note>
-## 6. Verify object storage upload
+## 5. Verify the session log
+
+For Beacon Cloud, open the dashboard's sessions view. The session appears under
+the environment's device a minute or two after the agent's turn ends.
For GCS, list the uploaded session objects:
@@ -400,6 +389,50 @@ harness.name=cursor
run.provider=cursor_cloud
```
+## What Beacon records
+
+From an agent's second turn on, Beacon records prompts, the agent's reasoning
+and replies, shell commands with their output and exit codes, file reads and
+edits, tool and MCP calls, subagent start and stop, compaction, and the end of
+each turn with its status (`completed`, `aborted`, or `error`).
+
+Cursor runs fewer hooks in cloud agents than in its desktop app, which leaves
+these gaps:
+
+- **First turn.** During an agent's first turn Cursor runs only the tool,
+ shell, file, and turn-end hooks. That turn's prompt, reasoning, and reply, and
+ the start and stop of any subagent it launches, are not recorded.
+- **Subagents.** A subagent's own events carry its own conversation id, so they
+ appear as a separate session. The agent's session records the subagent's start
+ and stop (from the second turn on), but nothing in Cursor's cloud hook
+ payloads ties the subagent's events back to the agent that started it.
+- **Web search.** Searches the agent runs did not fire any hook in our tests,
+ so they are not recorded.
+- **Session start and end.** Cursor does not run `sessionStart` or `sessionEnd`
+ in cloud agents. See [Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support).
+
+## Committing the hooks instead
+
+To keep Beacon's hooks in the repository, generate them, commit them, and keep
+the install script for the binary. The script sees the committed file and
+leaves it alone:
+
+```bash
+mkdir -p .cursor
+beacon cloud cursor print-hooks \
+ --binary-path /tmp/beacon/bin/beacon-hooks \
+ --log-path /tmp/beacon/runtime.jsonl > .cursor/hooks.json
+git add .cursor/hooks.json
+git commit -m "Add Beacon Cursor Cloud hooks"
+git push
+```
+
+Cursor also runs a repository's project hooks in local sessions, so everyone
+who opens the repository in Cursor runs committed hooks too. On their machines
+`/tmp/beacon/bin/beacon-hooks` does not exist, and Cursor lets the call through.
+If the repository already commits its own `.cursor/hooks.json`, add Beacon's
+entries to it.
+
## Security note
The self-serve flows create a dedicated GCS service account with
@@ -414,17 +447,20 @@ sensitive telemetry.
## Troubleshooting
-### The bucket is empty
+### Nothing arrives
-Confirm the Cursor setup script ran and installed binaries, and confirm the
-repository checkout includes committed project hooks:
+Confirm the environment has a successful Build and that the agent started after
+it. Then ask the agent to run:
```bash
-ls -la /tmp/beacon/bin
-ls -la .cursor
-sed -n '1,160p' .cursor/hooks.json
+ls -la /tmp/beacon/bin .cursor
+grep -v '^#' .git/info/exclude
```
+`/tmp/beacon/bin/beacon-hooks` and `.cursor/hooks.json` should both exist, and
+the exclude list should name `.cursor/hooks.json`. If they don't, the agent ran
+without Beacon's install script: check the Build's log.
+
Confirm hooks wrote telemetry:
```bash
@@ -432,9 +468,10 @@ 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 the GCS OAuth/storage endpoints or
-the regional S3 endpoint selected by `BEACON_CLOUD_UPLOAD=s3`.
+If `runtime.jsonl` exists but nothing arrives, check network access and
+credentials. The cloud VM must reach the Beacon Cloud ingest host, the GCS
+OAuth and storage endpoints, or the regional S3 endpoint, depending on where
+you send logs.
If `runtime.jsonl` does not exist, confirm the task used a Cursor Cloud
supported hook surface such as prompt submission, a file read, shell command,
@@ -444,13 +481,13 @@ its [Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-
### Cursor tries to commit hook settings
-The setup script should not modify `.cursor/hooks.json`. If a cloud agent shows
-changes to `.cursor/hooks.json`, update the setup script to `v0.0.56` or later
-and remove older commands that ran `beacon cloud cursor install-hooks` inside
-the VM.
+Beacon's install script lists `.cursor/hooks.json` in `.git/info/exclude`. If an
+agent shows `.cursor/hooks.json` as a change, the environment's install script
+predates that: regenerate it with `beacon cloud cursor print-setup` and paste it
+into the environment again.
```bash
-git diff -- .cursor/hooks.json
+git status --short -- .cursor
```
## Related
diff --git a/docs/runtimes/cursor.mdx b/docs/runtimes/cursor.mdx
index 90897083..5ce13a48 100644
--- a/docs/runtimes/cursor.mdx
+++ b/docs/runtimes/cursor.mdx
@@ -65,11 +65,11 @@ beacon endpoint hooks install --harness cursor --level project
| Area | 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 and uploads observed prompts immediately; the initial launch prompt can precede hook activation during bootstrap. 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. In Cursor Cloud, Beacon's install script writes the project hooks at Build time and prompts are uploaded as they happen; Cursor does not run the prompt hook in an agent's first turn, so the launch prompt is not recorded. See [Cursor's Cloud Agent hook support matrix](https://cursor.com/docs/hooks#cloud-agent-support). |
| Turn identity | Supported. Cursor's `generation_id`, which changes with every user message, is promoted to `prompt.id` on hook events |
| 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). |
| Pre-tool answer | `preToolUse`, `beforeShellExecution` and `beforeReadFile` answer `{"permission":"allow"}`, because Cursor's hooks reference does not make `permission` optional and blocks an action whose hook response does not match the schema. Cursor enforces only a hook's `deny`: an `allow` does not override your allowlist or approval mode, so a command Cursor would ask about still asks. A deny from a `BEACON_POLICY_PROVIDER` policy provider returns `{"permission":"deny"}` |
-| Agent responses | Supported for local and cloud Cursor through `afterAgentResponse` hooks. Each finished assistant message is recorded as an `agent.message` event with the reply text in `gen_ai.output.messages` (a `text` part) and a `content` marker, in the same turn (`prompt.id`) as the prompt that produced it. Cursor Cloud records them through the committed project hooks. `beacon endpoint cursor sync` also recovers committed assistant text |
+| Agent responses | Supported for local and cloud Cursor through `afterAgentResponse` hooks. Each finished assistant message is recorded as an `agent.message` event with the reply text in `gen_ai.output.messages` (a `text` part) and a `content` marker, in the same turn (`prompt.id`) as the prompt that produced it. Cursor Cloud records them through Beacon's project hooks from the second turn on. `beacon endpoint cursor sync` also recovers committed assistant text |
| Turn end | Supported for local and cloud Cursor through the `stop` hook, recorded as `tool.completed` ("Agent response completed") like every runtime's turn end. Cursor's `status` for the turn (`completed`, `aborted` or `error`) is kept verbatim as `turn.status`, so in the runtime log a stopped or failed turn can be told apart from a finished one, and a threat rule can match `e.turn.status`. The session view and shared traces do not show it yet |
| Agent reasoning telemetry | Supported for local and cloud 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`. |