Capture Cursor Cloud Agents with auspex

Last updated: August 31, 2026

This guide is for teams that run Cursor cloud agents — the Cursor-managed Linux VMs launched from cursor.com/agents, Cursor Desktop, Slack, or GitHub @cursor — and want that agent activity captured in Span, just like work on a laptop.

It installs the Span agent (auspex) on the cloud VM at startup, wires the Cursor capture hooks, and enrolls with Span. Setup is a small recipe committed to your repository plus one team-scoped secret.

This is for cloud agents. For engineers running Cursor on their own machine, use the macOS or Windows install guides (or your MDM). You can run both — auspex captures each surface once.

How it works

Cursor cloud agents run a configurable environment (install + start commands) when they spin up a VM. You can set that environment once at the team level so it applies to every repository — the recommended approach — or commit it per-repository. The auspex recipe uses that lifecycle to, on each agent VM:

  1. Fetch and verify the signed auspex binary (cosign-verified against an embedded trust root — a tampered or unsigned binary fails closed).
  2. Place one Cursor hook tier (system-level, falling back to user-level) — exactly one, so events are never double-captured.
  3. Run the supervised daemon and enroll with Span using your org token.
  4. Attribute events to the engineer who dispatched the agent — the work email is auto-discovered from Cursor's agent metadata, so no per-user secret is required.

Before you start

  • Admin access to your Cursor team's cloud-agent settings (to set a team environment + team secrets) — or, for the per-repository path, a repo you launch agents from.
  • Your Span org auth token (from your Span administrator — the global org token, not a personal access token).
  • The auspex download host (https://auspex.span.app, or the host your Span rep provided).

Step 1: Set up the environment

The reference recipe lives in the public auspex-distribution repository. Its scripts — install.sh (build phase: fetch + verify the binary, place one hook tier, arm the supervised daemon) and start.sh (run phase: resolve the engineer's email, launch the daemon) — are cosign-signed and published as GitHub Release assets (cursor-cloud-install.sh / -start.sh), so you run them from an immutable, signed URL.

Recommended: a team-level environment (applies to every repo)

In Cursor, go to Dashboard → Cloud Agents → Environments and create (or edit) your team environment. Set its commands to fetch and run the signed recipe — no per-repository files needed:

  • Install command:
curl -fsSL https://github.com/Attuned-Corp/auspex-distribution/releases/latest/download/cursor-cloud-install.sh | bash
  • Start command:
curl -fsSL https://github.com/Attuned-Corp/auspex-distribution/releases/latest/download/cursor-cloud-start.sh | bash

latest/download tracks the newest release; pin a specific tag (.../releases/download/<tag>/cursor-cloud-install.sh) for a reproducible setup. Each asset ships a .cosign.bundle so you can verify it before running (see the recipe README). This one team environment covers all repositories your team runs agents on.

Precedence: a repository that ships its own .cursor/environment.json overrides the team environment (Cursor resolves repo → personal → team, first match wins). So the team environment applies to every repo that doesn't define its own.

Alternative: per-repository

If a specific repo needs a bespoke setup, commit the recipe into its .cursor/ directory instead:

mkdir -p .cursor
# from a checkout of auspex-distribution:
cp examples/cursor-cloud/environment.json .cursor/environment.json
cp src/cursor-cloud/install.sh            .cursor/install.sh
cp src/cursor-cloud/start.sh              .cursor/start.sh
cp src/cursor-cloud/preflight.sh         .cursor/preflight.sh   # optional health check

Commit and push these to the branch you launch agents from — Cursor reads .cursor/environment.json from the launch branch, so an uncommitted file is not picked up.

Already using a custom base image? Use the Dockerfile variant — copy Dockerfile and environment.docker.json as well, then cp .cursor/environment.docker.json .cursor/environment.json. See the recipe README.

Step 2: Configure the secret and settings

In Cursor's cloud agent Secrets tab, set these at the team scope so they're shared across your team's agents (the token is a single org-wide credential — there's no reason to duplicate it per user):

Name Kind Scope Value
AUSPEX_CLOUD_TOKEN Runtime Secret Team your Span org auth token
AUSPEX_BASE_URL Runtime Secret or env var Team your auspex download host, e.g. https://auspex.span.app
AUSPEX_VERSION Runtime Secret or env var (optional) Team pin a release tag; leave unset to install the latest signed release
AUSPEX_VERIFY Runtime Secret or env var (optional) Team cosign (default) or checksum
  • AUSPEX_CLOUD_TOKEN must be a Runtime Secret so it's injected into the running agent and redacted from logs. Setting it at the team scope pairs naturally with the team environment from Step 1.
  • Set everything at the Team scope — the scope matters, not the kind. With the recommended no-image recipe, the install step runs in the agent context, so it sees team-scoped secrets (a Runtime Secret or an environment variable both work) but not user-scoped ones. A user-scoped AUSPEX_BASE_URL is invisible to install and the setup fails. (If you use the custom-image Dockerfile variant instead, a true image build sees only build args — pass AUSPEX_BASE_URL via --build-arg.)
  • No per-user email secret is needed — the engineer's work email is auto-discovered on each run. (You may set AUSPEX_CLOUD_WORK_EMAIL to override it, but it's optional.)

Step 3: Allowlist egress (only if your org restricts it)

Cursor cloud agents install, enroll, and export over the same endpoints as any auspex host, plus the install-time fetch. The complete list — hostnames and IP ranges, and how to shrink it — is maintained in one place: see Network Access → auspex in Cursor cloud agents in the security overview.

Step 4: Launch a normal cloud agent

Launch a cloud agent against the branch that carries the recipe, the way you normally would (from cursor.com/agents, Desktop, Slack, or GitHub @cursor).

Do not use the interactive "Set up agent" button — that is a separate, ephemeral setup mode. Launch a normal agent on your committed branch.

Step 5: Verify

Inside a running agent, run:

auspex status --verbose --check-token
bash .cursor/preflight.sh
  • auspex status should report the daemon reachable, capture wired, the token valid, and a single placement tier.
  • preflight.sh additionally confirms the token was injected as a secret and a work email resolved.

Then have the agent do some work (edit files, run commands) and confirm the trace appears in the Span dashboard. If you don't see anything yet, ask your Span rep to enable Agent Traces for your org.

Limitations

  • Session start: Cursor's sessionStart hook does not fire in the cloud agent's read-only startup phase; the first shell, file, and tool events are still captured.
  • Teardown: a burst of events in the final moments before the VM is destroyed may not flush.
  • Attribution scope: the work email is resolved once at startup (the agent's owner), so an agent driven by multiple people is attributed to its owner.

Troubleshooting

  • No events in Span — confirm AUSPEX_CLOUD_TOKEN is set as a Runtime Secret (check preflight.sh), the recipe files are committed on the launch branch, and egress to agent-traces.span.app is allowed.
  • Install failed fetching the binary — verify AUSPEX_BASE_URL is set and reachable, and that github.com is allowlisted (or set AUSPEX_VERIFY=checksum).
  • Events unattributed — the metadata-socket lookup may have failed; you can set AUSPEX_CLOUD_WORK_EMAIL explicitly as a fallback.
  • Two of every event — a second hook tier is present. The recipe places only one; remove any hooks you placed manually and re-run.

If you're stuck, share the agent's setup log and the output of auspex status --verbose with the Span team.