Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(agents): add Cursor Cloud environment (#16003)

Max Deichmann4983d27fddbd
diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md
index 95c4f893a1..2ac4383cf4 100644
--- a/.agents/AGENTS.md
+++ b/.agents/AGENTS.md
@@ -82,10 +82,24 @@ langfuse/
- shared: `pnpm --filter @langfuse/shared run test <file>`
- Build check: `pnpm run build:check`
- Full build: `pnpm run build`
-- Worktree bootstrap: `bash scripts/codex/setup.sh`
+- Shared agent/worktree bootstrap: `bash scripts/agents/setup.sh`
- Worktree maintenance: `bash scripts/codex/maintenance.sh`
- Install Playwright Chromium: `pnpm run playwright:install`
+### Cursor Cloud specific instructions
+
+- Cursor Cloud starts the complete source-built stack through
+ `scripts/agents/start-cursor-cloud.sh`; do not start a second web or worker
+ process on ports 3000 or 3030.
+- Use that script for the Cloud stack rather than invoking Compose directly:
+ the workspace `.env` contains host-facing `localhost` service URLs and must
+ not be used to interpolate container service configuration.
+- After changing web or worker production code, rerun
+ `bash scripts/agents/start-cursor-cloud.sh` before browser signoff.
+- Open a same-repo draft PR after local verification and test the resulting
+ `pr-<N>.preview.langfuse.com` deployment with synthetic data before marking
+ the PR ready. Previews normally run Mon-Fri 08:00-24:00 Europe/Berlin.
+
## Local Data Inspection
- For feature testing and debugging, inspect the local databases directly when
diff --git a/.agents/README.md b/.agents/README.md
index 327b357934..1530b03c9f 100644
--- a/.agents/README.md
+++ b/.agents/README.md
@@ -32,7 +32,7 @@ Current shape:
```json
{
"shared": {
- "setupScript": "bash scripts/codex/setup.sh",
+ "setupScript": "bash scripts/agents/setup.sh",
"devCommand": "pnpm run dev",
"devTerminalDescription": "Main development terminal running the development server"
},
@@ -85,6 +85,18 @@ Current shape:
},
"cursor": {
"environment": {
+ "name": "langfuse",
+ "user": "ubuntu",
+ "build": {
+ "dockerfile": "Dockerfile",
+ "context": ".."
+ },
+ "install": "bash scripts/agents/setup-cursor-cloud.sh",
+ "start": "bash scripts/agents/start-cursor-cloud.sh",
+ "ports": [
+ { "name": "Langfuse web", "port": 3000 },
+ { "name": "Langfuse worker health", "port": 3030 }
+ ],
"agentCanUpdateSnapshot": false
}
}
@@ -100,13 +112,18 @@ Generated local artifacts:
- `.claude/settings.json`
- `.claude/skills/*`
-- `.cursor/environment.json`
- `.cursor/mcp.json`
- `.vscode/mcp.json`
- `.mcp.json`
- `.codex/config.toml`
- `.codex/environments/environment.toml`
+Cursor must read its environment contract before it can run the install script,
+so `.cursor/environment.json` is the one generated configuration file committed
+to the repository. Generate it from `.agents/config.json`; never edit it by
+hand. `.cursor/Dockerfile` is also committed because it is an intentionally
+Cursor-specific runtime definition.
+
Discovery files are committed as symlinks, not generated locally, so a fresh
clone has guidance before `pnpm install` runs:
@@ -206,14 +223,71 @@ Update values in `shared`:
Only add tool-specific fields when they are required to generate a discovery
file for a supported tool. Keep the shared config minimal and neutral.
+## Cursor Cloud
+
+Cursor Cloud uses the committed environment file to build an Ubuntu 24.04
+machine with Node.js 24 and nested Docker support. Builds run
+`scripts/agents/setup-cursor-cloud.sh`, which delegates to the shared,
+idempotent setup and then installs Cursor's Playwright system dependencies.
+Each agent run starts the six-service source stack with
+`scripts/agents/start-cursor-cloud.sh`.
+
+The start script builds and waits for web, worker, PostgreSQL, ClickHouse,
+Redis, and MinIO, seeds the synthetic demo project, and verifies the web and
+worker health endpoints. The default Cursor VM is accepted only after three
+successful starts without OOMs or restart loops; otherwise use a larger
+Enterprise resource profile.
+
+The script deliberately prevents the workspace `.env` and exported application
+variables from participating in Compose interpolation. That file configures
+host processes with `localhost` service URLs, while containers must use Compose
+service names such as `postgres`, `clickhouse`, and `redis`. Only Docker client
+and public build controls are passed into Compose. The seed command also receives
+explicit local connection URLs so an exported secret cannot redirect it to an
+external database.
+
+### Cursor team tools
+
+Repository files cannot publish or authenticate Cursor Team Marketplace MCPs.
+A team admin must configure these under **Dashboard > Integrations & MCP**.
+Use HTTP/OAuth where available so credentials remain outside the agent VM.
+
+| Tool group | Cursor distribution | Default policy |
+| --- | --- | --- |
+| GitHub | Cursor GitHub App | Enabled for same-repo branches, draft PRs, CI, and preview status |
+| Langfuse Docs | Shared HTTP MCP | Enabled, read-only |
+| Linear | Shared OAuth MCP | Enabled; allow read/search tools only |
+| Datadog EU and US | Team Marketplace MCPs | Enabled; allow logs, metrics, traces, dashboards, and monitor reads only |
+| Metabase | Team Marketplace MCP | Enabled; allow metadata and query reads only |
+| Pylon | Team Marketplace MCP | Enabled; allow issue/thread/customer reads only |
+| incident.io | Team Marketplace MCP | Enabled; allow incident, alert, and follow-up reads only |
+| ClickHouse Cloud | Team Marketplace MCP | Enabled; allow organization, service, query, and status reads only |
+| Circleback | Team Marketplace MCP | Enabled; allow meeting, transcript, calendar, email, and action-item reads only |
+| Slack | Cursor Marketplace integration | Enabled; allow search/history/channel reads only |
+| Google Drive | Cursor Marketplace integration | Enabled; allow file search, metadata, export, and content reads only |
+| PostHog | Cursor Marketplace integration | Enabled; allow analytics, schema, query, and insight reads only |
+| Browser automation | Cursor computer use in Cloud; Playwright MCP locally | Enabled; never reuse a developer's local authenticated browser session |
+
+Do not approve create, save, update, delete, comment, reply, send, resolve,
+archive, acknowledge, execute-DDL, or settings-management tools. Review the
+server's discovered tool list whenever an MCP version changes; naming heuristics
+do not replace an explicit allowlist. Production/support data must not be copied
+into public preview accounts or Cursor PR artifacts.
+
+Use `Default + allowlist` network mode. Include the package and container
+registries used by the Dockerfile and Compose stack, GitHub, Langfuse preview
+hosts, and `cloud-agent-artifacts.s3.us-east-1.amazonaws.com` when PR artifacts
+are enabled. Do not grant Cursor AWS/EKS credentials for preview wakeups;
+preview QA runs during Mon-Fri 08:00-24:00 Europe/Berlin.
+
## Workflow
After editing `.agents/config.json`:
1. Run `pnpm run agents:sync`
2. Run `pnpm run agents:check`
-3. Verify you did not stage any generated files under `.claude/skills/` or the
- generated MCP/runtime config paths
+3. Commit `.cursor/environment.json` when its canonical input changes, but do
+ not stage other generated MCP/runtime config or `.claude/skills/` outputs
4. Update `AGENTS.md` or `CONTRIBUTING.md` if the shared workflow materially
changed
diff --git a/.agents/config.json b/.agents/config.json
index 288b6fff4e..18bb193c96 100644
--- a/.agents/config.json
+++ b/.agents/config.json
@@ -1,6 +1,6 @@
{
"shared": {
- "setupScript": "bash scripts/codex/setup.sh",
+ "setupScript": "bash scripts/agents/setup.sh",
"devCommand": "pnpm run dev",
"devTerminalDescription": "Main development terminal running the development server"
},
@@ -53,6 +53,24 @@
},
"cursor": {
"environment": {
+ "name": "langfuse",
+ "user": "ubuntu",
+ "build": {
+ "dockerfile": "Dockerfile",
+ "context": ".."
+ },
+ "install": "bash scripts/agents/setup-cursor-cloud.sh",
+ "start": "bash scripts/agents/start-cursor-cloud.sh",
+ "ports": [
+ {
+ "name": "Langfuse web",
+ "port": 3000
+ },
+ {
+ "name": "Langfuse worker health",
+ "port": 3030
+ }
+ ],
"agentCanUpdateSnapshot": false
}
}
diff --git a/.agents/skills/frontend-browser-review/SKILL.md b/.agents/skills/frontend-browser-review/SKILL.md
index 805e480d47..8503664ed5 100644
--- a/.agents/skills/frontend-browser-review/SKILL.md
+++ b/.agents/skills/frontend-browser-review/SKILL.md
@@ -3,7 +3,7 @@ name: frontend-browser-review
description: |
Shared workflow for browser-based review of user-visible frontend changes in Langfuse.
Use when a change affects UI behavior, layout, styling, navigation, or browser-visible
- regressions and should be checked with the Playwright MCP server before signoff.
+ regressions and should be checked with available browser automation before signoff.
---
# Frontend Browser Review
@@ -14,8 +14,8 @@ Use this skill when a change affects what users see or do in the browser.
- Read [`../../../web/AGENTS.md`](../../../web/AGENTS.md) for web-specific
entry points and test commands.
-- Use the workspace `playwright` MCP server configured from the repo-owned
- shared agent setup.
+- In Cursor Cloud, use built-in computer use. In local agent environments, use
+ the workspace `playwright` MCP server from the shared agent setup.
## When To Use It
@@ -42,12 +42,12 @@ Do not hand-write seed scripts or raw ClickHouse inserts.
## Review Loop
-1. Start the app with `pnpm run dev:web` unless an existing local server is
- already running.
+1. Use the existing Cursor Cloud Compose app when available. Otherwise start
+ the app with `pnpm run dev:web` unless a local server is already running.
2. Install Chromium with `pnpm run playwright:install` if Playwright has not
been set up on the machine yet.
-3. Open the primary changed flow with the Playwright MCP server, using the
- deep links printed by the seed CLI when the flow needs seeded data.
+3. Open the primary changed flow with Cursor computer use or the Playwright MCP
+ server, using seed-CLI deep links when the flow needs seeded data.
4. Exercise the main happy path affected by the change.
5. Check for obvious visual regressions:
- broken layout or spacing
@@ -56,8 +56,8 @@ Do not hand-write seed scripts or raw ClickHouse inserts.
- broken responsive behavior on narrow widths
6. If the page changed materially, inspect the resulting UI state and compare
it against the intended behavior from the task or existing patterns.
-7. If the browser session fails, inspect traces and artifacts under
- `/tmp/playwright-mcp`.
+7. If a Playwright MCP session fails, inspect `/tmp/playwright-mcp`. In Cursor
+ Cloud, inspect the run's browser artifacts and Compose logs.
## Output Expectations
diff --git a/.cursor/Dockerfile b/.cursor/Dockerfile
new file mode 100644
index 0000000000..1cd6e05fba
--- /dev/null
+++ b/.cursor/Dockerfile
@@ -0,0 +1,81 @@
+FROM --platform=${BUILDPLATFORM} golang:1.24 AS migrate-builder
+
+ARG TARGETOS
+ARG TARGETARCH
+ENV CGO_ENABLED=0 \
+ GOBIN=/out \
+ GOOS=${TARGETOS} \
+ GOARCH=${TARGETARCH}
+
+RUN /usr/local/go/bin/go install -trimpath -tags 'clickhouse' -ldflags='-s -w' \
+ github.com/golang-migrate/migrate/v4/cmd/[email protected]
+
+FROM ubuntu:24.04
+
+ARG DOCKER_VERSION=5:28.5.2-1~ubuntu.24.04~noble
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ build-essential \
+ ca-certificates \
+ curl \
+ git \
+ gh \
+ gnupg \
+ iptables \
+ jq \
+ openssh-client \
+ python3 \
+ sudo \
+ unzip \
+ wget \
+ fuse-overlayfs \
+ && rm -rf /var/lib/apt/lists/*
+
+# Install Node.js 24 from NodeSource and activate the repository's pinned pnpm.
+RUN install -m 0755 -d /etc/apt/keyrings \
+ && curl --retry 3 --retry-delay 5 -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
+ | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_24.x nodistro main" \
+ > /etc/apt/sources.list.d/nodesource.list \
+ && apt-get update \
+ && apt-get install -y --no-install-recommends nodejs \
+ && npm install --global [email protected] \
+ && corepack enable \
+ && corepack prepare [email protected] --activate \
+ && rm -rf /var/lib/apt/lists/*
+
+# Cursor Cloud runs Docker inside its own container layer. fuse-overlayfs and
+# legacy iptables avoid the common nested-Docker storage and networking faults.
+RUN install -m 0755 -d /etc/apt/keyrings \
+ && curl --retry 3 --retry-delay 5 -fsSL https://download.docker.com/linux/ubuntu/gpg \
+ | gpg --dearmor -o /etc/apt/keyrings/docker.gpg \
+ && chmod a+r /etc/apt/keyrings/docker.gpg \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu noble stable" \
+ > /etc/apt/sources.list.d/docker.list \
+ && apt-get update \
+ && apt-get install -y --no-install-recommends \
+ docker-ce=${DOCKER_VERSION} \
+ docker-ce-cli=${DOCKER_VERSION} \
+ containerd.io \
+ docker-buildx-plugin \
+ docker-compose-plugin \
+ && rm -rf /var/lib/apt/lists/*
+
+RUN mkdir -p /etc/docker \
+ && printf '%s\n' '{' ' "storage-driver": "fuse-overlayfs"' '}' > /etc/docker/daemon.json \
+ && update-alternatives --set iptables /usr/sbin/iptables-legacy \
+ && update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
+
+RUN id -u ubuntu >/dev/null 2>&1 || useradd -m -s /bin/bash ubuntu \
+ && groupadd -f docker \
+ && usermod -aG docker,sudo ubuntu \
+ && echo "ubuntu ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/ubuntu \
+ && chmod 0440 /etc/sudoers.d/ubuntu
+
+COPY --from=migrate-builder /out/migrate /usr/local/bin/migrate
+COPY scripts/agents/clickhouse-client.sh /usr/local/bin/clickhouse
+RUN chmod 0755 /usr/local/bin/migrate /usr/local/bin/clickhouse
+
+USER ubuntu
+WORKDIR /home/ubuntu
diff --git a/.cursor/environment.json b/.cursor/environment.json
new file mode 100644
index 0000000000..a3a56fe09c
--- /dev/null
+++ b/.cursor/environment.json
@@ -0,0 +1,22 @@
+{
+ "$schema": "https://www.cursor.com/schemas/environment.schema.json",
+ "name": "langfuse",
+ "user": "ubuntu",
+ "build": {
+ "dockerfile": "Dockerfile",
+ "context": ".."
+ },
+ "install": "bash scripts/agents/setup-cursor-cloud.sh",
+ "start": "bash scripts/agents/start-cursor-cloud.sh",
+ "ports": [
+ {
+ "name": "Langfuse web",
+ "port": 3000
+ },
+ {
+ "name": "Langfuse worker health",
+ "port": 3030
+ }
+ ],
+ "agentCanUpdateSnapshot": false
+}
diff --git a/.gitignore b/.gitignore
index debf78fc85..2dfda37a5c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -92,7 +92,6 @@ web/test-results/*
.claude/skills/
.claude/launch.json
.cursor/mcp.json
-.cursor/environment.json
.vscode/mcp.json
.codex/config.toml
.codex/environments/environment.toml
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c11ca91709..2aa334f455 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -163,6 +163,28 @@ Notes:
PostgreSQL, Redis, ClickHouse, and object storage, plus matching environment
variables in the Codex UI.
+### Cursor Cloud Setup
+
+Cursor Cloud Agents use the committed `.cursor/environment.json` and
+`.cursor/Dockerfile`. The environment build runs the shared setup script, and
+each agent run starts a branch-built six-service Docker Compose stack:
+
+```bash
+bash scripts/agents/setup.sh
+bash scripts/agents/start-cursor-cloud.sh
+```
+
+The start command waits for web, worker, PostgreSQL, ClickHouse, Redis, and
+MinIO, then seeds the synthetic demo project and checks both application health
+endpoints. Cursor team administrators separately configure the read-only MCP
+catalog described in `.agents/README.md`; credentials and OAuth grants belong
+in Cursor, never in repository files.
+
+After local verification, a Cursor agent should open a same-repo draft PR and
+test its `pr-<N>.preview.langfuse.com` deployment before marking it ready.
+Preview data and any attached artifacts must remain synthetic. Previews normally
+run Mon-Fri 08:00-24:00 Europe/Berlin and are not woken with Cursor credentials.
+
### Shared Agent Setup
This repository keeps the shared agent setup in source control so developers
@@ -185,17 +207,20 @@ MCP server catalog.
- Tool-specific runtime shims generated locally from the shared config and not committed:
- `.claude/settings.json`
- `.codex/environments/environment.toml`
+- Cursor runtime contract generated from shared config and committed because
+ Cursor needs it before install:
- `.cursor/environment.json`
- Tool-specific skill projections generated locally and not committed:
- `.claude/skills/*`
-- Shared bootstrap for agent environments: `bash scripts/codex/setup.sh`
+- Shared bootstrap for agent environments: `bash scripts/agents/setup.sh`
When you change the shared MCP setup:
1. Edit `.agents/config.json`
2. Run `pnpm run agents:sync`
3. Run `pnpm run agents:check`
-4. Do not commit the generated MCP config files or runtime shims
+4. Commit `.cursor/environment.json` when it changes; do not commit the other
+ generated MCP config files or runtime shims
**Steps**
diff --git a/scripts/agents/clickhouse-client.sh b/scripts/agents/clickhouse-client.sh
new file mode 100755
index 0000000000..52616b4f8d
--- /dev/null
+++ b/scripts/agents/clickhouse-client.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+container_id="$(docker ps --filter label=com.docker.compose.service=clickhouse --format '{{.ID}}' | head -n 1)"
+
+if [ -z "$container_id" ]; then
+ echo "No running Docker Compose ClickHouse service found." >&2
+ exit 1
+fi
+
+exec docker exec -i "$container_id" clickhouse "$@"
diff --git a/scripts/agents/setup-cursor-cloud.sh b/scripts/agents/setup-cursor-cloud.sh
new file mode 100755
index 0000000000..db84be4277
--- /dev/null
+++ b/scripts/agents/setup-cursor-cloud.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+cd "$repo_root"
+bash scripts/agents/setup.sh
+
+# Cursor's custom Ubuntu image needs Playwright's system libraries. Keep this
+# privileged host mutation out of the shared Codex and local setup path.
+pnpm --filter web exec playwright install-deps chromium
diff --git a/scripts/agents/setup.sh b/scripts/agents/setup.sh
new file mode 100755
index 0000000000..4510971f26
--- /dev/null
+++ b/scripts/agents/setup.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ensure_env_file() {
+ local target_path="$1"
+ local fallback_path="$2"
+
+ if [ -f "$target_path" ]; then
+ return 0
+ fi
+
+ cp "$fallback_path" "$target_path"
+}
+
+if ! command -v corepack >/dev/null 2>&1; then
+ echo "corepack is required. Use an environment with Node.js 24 support."
+ exit 1
+fi
+
+corepack enable
+corepack prepare [email protected] --activate
+
+ensure_env_file .env .env.dev.example
+ensure_env_file .env.test .env.test.example
+
+pnpm install --frozen-lockfile
+
+if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+ if ! docker image inspect "langfuse-in-app-agent-sandbox:latest" >/dev/null 2>&1; then
+ rm -f "packages/in-app-agent-sandbox-runtime/.local-image-built"
+ fi
+
+ pnpm turbo run build:docker-image --filter @repo/in-app-agent-sandbox-runtime --output-logs errors-only
+else
+ echo "Skipping local in-app agent sandbox image build because Docker is not available."
+fi
+
+# Install Chromium into the default user-level Playwright cache so frontend
+# browser review works on first bootstrap. Provider-specific OS dependencies
+# belong in the provider setup rather than this shared script.
+pnpm run playwright:install
+
+# Generate the shared Prisma client explicitly in the current worktree before
+# the workspace-wide db:generate task, which may be satisfied by Turbo cache.
+pnpm --filter=shared run db:generate
+
+# Prisma client generation is needed for typecheck/build tasks.
+pnpm run db:generate
diff --git a/scripts/agents/start-cursor-cloud.sh b/scripts/agents/start-cursor-cloud.sh
new file mode 100755
index 0000000000..6abbe06a9e
--- /dev/null
+++ b/scripts/agents/start-cursor-cloud.sh
@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+compose_file="${CURSOR_COMPOSE_FILE:-$repo_root/docker-compose.build.yml}"
+wait_timeout="${CURSOR_COMPOSE_WAIT_TIMEOUT_SECONDS:-600}"
+compose_project_name="${CURSOR_COMPOSE_PROJECT_NAME:-langfuse-cursor}"
+
+# The workspace .env is for processes running on the host and therefore uses
+# localhost service URLs. Compose services need container-network hostnames.
+# Start from a clean environment and explicitly preserve only Docker and
+# public build controls that are safe inputs to this self-contained stack.
+compose_env=(
+ "HOME=$HOME"
+ "PATH=$PATH"
+ "COMPOSE_PROJECT_NAME=$compose_project_name"
+)
+
+for variable_name in \
+ BUILDKIT_PROGRESS \
+ DOCKER_CERT_PATH \
+ DOCKER_CONFIG \
+ DOCKER_CONTEXT \
+ DOCKER_HOST \
+ DOCKER_TLS_VERIFY \
+ NEXT_PUBLIC_LANGFUSE_CLOUD_REGION \
+ XDG_CONFIG_HOME; do
+ if declare -p "$variable_name" >/dev/null 2>&1; then
+ compose_env+=("$variable_name=${!variable_name}")
+ fi
+done
+
+compose() {
+ env -i "${compose_env[@]}" \
+ docker compose --env-file /dev/null -f "$compose_file" "$@"
+}
+
+dump_diagnostics() {
+ local exit_code=$?
+ trap - ERR
+ set +e
+
+ echo "Cursor Cloud stack startup failed; collecting Docker diagnostics."
+ docker info
+ compose ps -a
+ compose logs --tail=200 langfuse-web langfuse-worker postgres clickhouse redis minio
+
+ exit "$exit_code"
+}
+
+trap dump_diagnostics ERR
+
+if ! docker info >/dev/null 2>&1; then
+ sudo service docker start
+fi
+
+for _ in $(seq 1 60); do
+ if docker info >/dev/null 2>&1; then
+ break
+ fi
+ sleep 1
+done
+
+docker info >/dev/null
+
+compose up -d --build --wait --wait-timeout "$wait_timeout"
+
+cd "$repo_root"
+env -i \
+ "HOME=$HOME" \
+ "PATH=$PATH" \
+ "DATABASE_URL=postgresql://postgres:[email protected]:5432/postgres" \
+ "DIRECT_URL=postgresql://postgres:[email protected]:5432/postgres" \
+ "CLICKHOUSE_MIGRATION_URL=clickhouse://127.0.0.1:9000" \
+ "CLICKHOUSE_URL=http://127.0.0.1:8123" \
+ "CLICKHOUSE_USER=clickhouse" \
+ "CLICKHOUSE_PASSWORD=clickhouse" \
+ "REDIS_HOST=127.0.0.1" \
+ "REDIS_PORT=6379" \
+ "REDIS_AUTH=myredissecret" \
+ pnpm --filter=shared run db:seed
+
+curl --fail --silent --show-error "http://127.0.0.1:3000/api/public/health" >/dev/null
+curl --fail --silent --show-error "http://127.0.0.1:3030/api/health" >/dev/null
+
+compose ps
+trap - ERR
+
+echo "Cursor Cloud Langfuse stack is healthy: 6 services, web :3000, worker :3030."
diff --git a/scripts/agents/start-cursor-cloud.test.sh b/scripts/agents/start-cursor-cloud.test.sh
new file mode 100755
index 0000000000..07dc822eed
--- /dev/null
+++ b/scripts/agents/start-cursor-cloud.test.sh
@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+tmpdir="$(mktemp -d)"
+command_log="$tmpdir/commands.log"
+docker_ready="$tmpdir/docker-ready"
+
+cleanup() {
+ rm -rf "$tmpdir"
+}
+
+trap cleanup EXIT
+mkdir -p "$tmpdir/bin"
+
+cat <<EOF > "$tmpdir/bin/docker"
+#!/usr/bin/env bash
+printf 'docker %s\n' "\$*" >> "$command_log"
+if [ "\${1:-}" = "compose" ]; then
+ printf 'compose DATABASE_URL=%s\n' "\${DATABASE_URL-<unset>}" >> "$command_log"
+fi
+if [ "\${1:-}" = "info" ] && [ ! -f "$docker_ready" ]; then
+ exit 1
+fi
+exit 0
+EOF
+
+cat <<EOF > "$tmpdir/bin/service"
+#!/usr/bin/env bash
+printf 'service %s\n' "\$*" >> "$command_log"
+touch "$docker_ready"
+EOF
+
+cat <<EOF > "$tmpdir/bin/pnpm"
+#!/usr/bin/env bash
+printf 'pnpm %s\n' "\$*" >> "$command_log"
+printf 'pnpm DATABASE_URL=%s CLICKHOUSE_URL=%s\n' "\${DATABASE_URL-<unset>}" "\${CLICKHOUSE_URL-<unset>}" >> "$command_log"
+EOF
+
+cat <<EOF > "$tmpdir/bin/curl"
+#!/usr/bin/env bash
+printf 'curl %s\n' "\$*" >> "$command_log"
+EOF
+
+cat <<'EOF' > "$tmpdir/bin/sudo"
+#!/usr/bin/env bash
+exec "$@"
+EOF
+
+chmod +x "$tmpdir/bin/docker" "$tmpdir/bin/service" "$tmpdir/bin/pnpm" "$tmpdir/bin/curl" "$tmpdir/bin/sudo"
+
+PATH="$tmpdir/bin:$PATH" \
+DATABASE_URL="postgresql://external.example:5432/production" \
+CLICKHOUSE_URL="https://external.example:8443" \
+CURSOR_COMPOSE_WAIT_TIMEOUT_SECONDS=321 \
+ bash "$repo_root/scripts/agents/start-cursor-cloud.sh"
+
+assert_command() {
+ local expected="$1"
+ if ! grep -Fq -- "$expected" "$command_log"; then
+ echo "Missing command: $expected"
+ cat "$command_log"
+ exit 1
+ fi
+}
+
+assert_command "service docker start"
+assert_command "docker compose --env-file /dev/null -f $repo_root/docker-compose.build.yml up -d --build --wait --wait-timeout 321"
+assert_command "compose DATABASE_URL=<unset>"
+assert_command "pnpm --filter=shared run db:seed"
+assert_command "pnpm DATABASE_URL=postgresql://postgres:[email protected]:5432/postgres CLICKHOUSE_URL=http://127.0.0.1:8123"
+assert_command "curl --fail --silent --show-error http://127.0.0.1:3000/api/public/health"
+assert_command "curl --fail --silent --show-error http://127.0.0.1:3030/api/health"
+
+assert_file_contains() {
+ local expected="$1"
+ if ! grep -Fq -- "$expected" "$repo_root/docker-compose.build.yml"; then
+ echo "Customer Compose default changed: missing $expected"
+ exit 1
+ fi
+}
+
+assert_file_contains '"3000:3000"'
+assert_file_contains '"3030:3030"'
+assert_file_contains '"8123:8123"'
+assert_file_contains '"9000:9000"'
+assert_file_contains '"9090:9000"'
+assert_file_contains '"9091:9001"'
+assert_file_contains '6379:6379'
+assert_file_contains '5432:5432'
+
+echo "Cursor Cloud startup command regression test passed"
diff --git a/scripts/agents/sync-agent-shims.mjs b/scripts/agents/sync-agent-shims.mjs
index 948bf09d78..67852d8fba 100644
--- a/scripts/agents/sync-agent-shims.mjs
+++ b/scripts/agents/sync-agent-shims.mjs
@@ -136,15 +136,14 @@ const formatClaudeSettings = () =>
const formatCursorEnvironment = () =>
JSON.stringify(
{
+ $schema: "https://www.cursor.com/schemas/environment.schema.json",
+ name: config.cursor.environment.name,
+ user: config.cursor.environment.user,
+ build: config.cursor.environment.build,
+ install: config.cursor.environment.install ?? config.shared.setupScript,
+ start: config.cursor.environment.start,
+ ports: config.cursor.environment.ports,
agentCanUpdateSnapshot: config.cursor.environment.agentCanUpdateSnapshot,
- install: config.shared.setupScript,
- terminals: [
- {
- name: "Development Terminal",
- command: config.shared.devCommand,
- description: config.shared.devTerminalDescription,
- },
- ],
},
null,
2,
diff --git a/scripts/codex/setup.sh b/scripts/codex/setup.sh
index b3b620c3e2..bb271bcbe9 100755
--- a/scripts/codex/setup.sh
+++ b/scripts/codex/setup.sh
@@ -2,47 +2,6 @@
set -euo pipefail
-ensure_env_file() {
- local target_path="$1"
- local fallback_path="$2"
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
- if [ -f "$target_path" ]; then
- return 0
- fi
-
- cp "$fallback_path" "$target_path"
-}
-
-if ! command -v corepack >/dev/null 2>&1; then
- echo "corepack is required. Use an environment with Node.js 24 support."
- exit 1
-fi
-
-corepack enable
-corepack prepare [email protected] --activate
-
-ensure_env_file .env .env.dev.example
-ensure_env_file .env.test .env.test.example
-
-pnpm install --frozen-lockfile
-
-if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
- if ! docker image inspect "langfuse-in-app-agent-sandbox:latest" >/dev/null 2>&1; then
- rm -f "packages/in-app-agent-sandbox-runtime/.local-image-built"
- fi
-
- pnpm turbo run build:docker-image --filter @repo/in-app-agent-sandbox-runtime --output-logs errors-only
-else
- echo "Skipping local in-app agent sandbox image build because Docker is not available."
-fi
-
-# Install Chromium into the default user-level Playwright cache so frontend
-# browser review works on first bootstrap.
-pnpm run playwright:install
-
-# Generate the shared Prisma client explicitly in the current worktree before
-# the workspace-wide db:generate task, which may be satisfied by Turbo cache.
-pnpm --filter=shared run db:generate
-
-# Prisma client generation is needed for typecheck/build tasks.
-pnpm run db:generate
+exec bash "$repo_root/scripts/agents/setup.sh" "$@"
diff --git a/scripts/codex/setup.test.sh b/scripts/codex/setup.test.sh
index 3a0701d6ef..0693c898ea 100755
--- a/scripts/codex/setup.test.sh
+++ b/scripts/codex/setup.test.sh
@@ -14,13 +14,18 @@ trap cleanup EXIT
repo_copy="$tmpdir/repo"
pnpm_log="$tmpdir/pnpm.log"
-mkdir -p "$tmpdir/bin" "$repo_copy/scripts/codex"
+mkdir -p "$tmpdir/bin" "$repo_copy/scripts/agents" "$repo_copy/scripts/codex"
+cp "$repo_root/scripts/agents/setup.sh" "$repo_copy/scripts/agents/setup.sh"
+cp "$repo_root/scripts/agents/setup-cursor-cloud.sh" "$repo_copy/scripts/agents/setup-cursor-cloud.sh"
cp "$repo_root/scripts/codex/setup.sh" "$repo_copy/scripts/codex/setup.sh"
cp "$repo_root/.env.dev.example" "$repo_copy/.env.dev.example"
cp "$repo_root/.env.test.example" "$repo_copy/.env.test.example"
-chmod +x "$repo_copy/scripts/codex/setup.sh"
+chmod +x \
+ "$repo_copy/scripts/agents/setup.sh" \
+ "$repo_copy/scripts/agents/setup-cursor-cloud.sh" \
+ "$repo_copy/scripts/codex/setup.sh"
cat <<'EOF' > "$tmpdir/bin/corepack"
#!/usr/bin/env bash
@@ -33,7 +38,12 @@ printf '%s\n' "\$*" >> "$pnpm_log"
exit 0
EOF
-chmod +x "$tmpdir/bin/corepack" "$tmpdir/bin/pnpm"
+cat <<'EOF' > "$tmpdir/bin/uname"
+#!/usr/bin/env bash
+echo Linux
+EOF
+
+chmod +x "$tmpdir/bin/corepack" "$tmpdir/bin/pnpm" "$tmpdir/bin/uname"
assert_file_contains() {
local file_path="$1"
@@ -90,7 +100,7 @@ assert_file_contains \
assert_file_contains \
"$pnpm_log" \
"run playwright:install" \
- "setup.sh should install Playwright browsers for frontend review"
+ "shared setup should install Playwright without changing host packages"
assert_file_contains \
"$pnpm_log" \
@@ -102,4 +112,14 @@ assert_file_contains \
"run db:generate" \
"setup.sh should generate Prisma artifacts"
+(
+ cd "$repo_copy"
+ PATH="$tmpdir/bin:$PATH" bash scripts/agents/setup-cursor-cloud.sh
+)
+
+assert_file_contains \
+ "$pnpm_log" \
+ "--filter web exec playwright install-deps chromium" \
+ "Cursor Cloud setup should install Playwright's Linux dependencies"
+
echo "setup.sh example bootstrap regression test passed"