Cursor Cloud Agents

Cursor Cloud Agents run outside your managed endpoints, so they do not inherit AI Watch binaries, MDM settings, or endpoint hooks. Use the Cursor Cloud hook collector to send supported session events to Runlayer. This integration is monitor-only. It cannot block tools, enforce MCP policy, read Runlayer data, or administer your workspace. The first prompt can run before repository hooks initialize, and Cursor Cloud does not currently emit sessionStart or sessionEnd, so session coverage is degraded.

1. Create a scoped key

In Runlayer, go to Settings → Organization API Keys, create a key with only the Cursor Cloud Hooks permission, and copy it when shown. Runlayer stores only its hash. Creating a replacement and revoking the old key rotates access without deleting historical sessions. Add the value to your Cursor Cloud environment or team secret store as RUNLAYER_CURSOR_CLOUD_HOOK_KEY. Do not commit it to the repository, and do not use an AI Watch organization key or Agent Account secret.

2. Add the hook helper

Create .cursor/runlayer_cloud_hook.py in the repository. Replace the hostname in COLLECTOR_URL with your Runlayer tenant hostname. Keep the full HTTPS URL literal so repository content cannot redirect credentials to another host.

#!/usr/bin/env python3
import os
import sys
import time
import urllib.error
import urllib.request
import uuid

COLLECTOR_URL = "https://YOUR-TENANT.runlayer.com/api/v1/hooks/cursor-cloud/events"
MAX_PAYLOAD_BYTES = 256 * 1024
ALLOW = '{"permission":"allow"}'


class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None


def deliver(payload: bytes, key: str) -> None:
    delivery_id = str(uuid.uuid4())
    request = urllib.request.Request(
        COLLECTOR_URL,
        data=payload,
        method="POST",
        headers={
            "Content-Type": "application/json",
            "X-Runlayer-Delivery-ID": delivery_id,
            "x-runlayer-api-key": key,
        },
    )
    opener = urllib.request.build_opener(NoRedirect)
    for attempt, delay in enumerate((0, 0.2, 0.8)):
        if delay:
            time.sleep(delay)
        try:
            with opener.open(request, timeout=2) as response:
                if 200 <= response.status < 300:
                    return
        except urllib.error.HTTPError as error:
            if error.code < 500 and error.code != 429:
                return
            if attempt == 2:
                return
        except (urllib.error.URLError, TimeoutError):
            if attempt == 2:
                return


def main() -> int:
    try:
        payload = sys.stdin.buffer.read(MAX_PAYLOAD_BYTES + 1)
        key = os.environ.get("RUNLAYER_CURSOR_CLOUD_HOOK_KEY", "")
        if key and len(payload) <= MAX_PAYLOAD_BYTES:
            deliver(payload, key)
    except Exception:
        pass
    sys.stdout.write(ALLOW)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

The helper reuses one delivery ID across transient retries, never logs the key or payload, and always returns Cursor’s explicit allow response. A Runlayer outage therefore cannot block or change a Cloud Agent run.

3. Register live Cloud events

Add these entries to .cursor/hooks.json, preserving any existing hooks:

{
  "version": 1,
  "hooks": {
    "beforeReadFile": [{ "command": "python3 .cursor/runlayer_cloud_hook.py" }],
    "beforeSubmitPrompt": [{ "command": "python3 .cursor/runlayer_cloud_hook.py" }],
    "afterAgentThought": [{ "command": "python3 .cursor/runlayer_cloud_hook.py" }],
    "preToolUse": [{ "command": "python3 .cursor/runlayer_cloud_hook.py" }],
    "postToolUse": [{ "command": "python3 .cursor/runlayer_cloud_hook.py" }],
    "afterAgentResponse": [{ "command": "python3 .cursor/runlayer_cloud_hook.py" }],
    "stop": [{ "command": "python3 .cursor/runlayer_cloud_hook.py" }]
  }
}

Run a follow-up prompt after the Cloud environment is ready, then open Sessions in Runlayer and filter for Cursor Cloud Agents. If events do not appear, confirm Cursor is enabled under Settings → Agent session monitoring, the secret is present in the Cloud environment, and the collector URL uses the correct tenant hostname.

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Cursor Cloud Agents

1. Create a scoped key

2. Add the hook helper

3. Register live Cloud events

​1. Create a scoped key

​2. Add the hook helper

​3. Register live Cloud events

1. Create a scoped key

2. Add the hook helper

3. Register live Cloud events