Cursor Enterprise Onboarding
Enterprise Deployment Guide

Self-Managed Cloud Agent Pool

A decision and rollout guide for platform, security, and engineering leaders evaluating a centrally managed pool of self-hosted Cloud Agent workers. Keep code execution, build artifacts, and secrets inside your network while Cursor handles orchestration, model access, and the Cloud Agent experience.

Audience: Platform Engineering, Security, Engineering Leadership
Prerequisite: Phase 1 governance complete; Phase 3 readiness
Outcome: Governed, scalable async agent capacity in your infrastructure

How to Use This Guide

Self-hosted Cloud Agents are an Enterprise capability for teams that need async agent workflows without sending tool execution outside the corporate boundary. Use this page to align stakeholders on the decision, confirm readiness, design the pool architecture, and execute a phased rollout with measurable exit criteria.

1 · Decide

Compare Cursor-hosted vs. self-managed execution. Confirm security, compliance, and SDLC fit before committing infrastructure.

2 · Prepare

Validate Enterprise prerequisites: Privacy Mode, SSO/SCIM, service accounts, network egress, and approved use cases.

3 · Roll out

Stand up a pilot pool, enable dashboard routing, expand via IdP groups, and operationalize monitoring and autoscaling.

Pair with the onboarding plan

This guide deep-dives on self-managed pools — it does not replace Phase 1 governance or Phase 3 expansion. Complete identity, spend controls, and pilot ROI validation first. Your Solutions Architect should lead the architecture review; your ADM owns executive alignment and adoption metrics.

Decision framework

When to Use a Self-Managed Pool

Cursor offers three Cloud Agent execution models. A self-managed pool is the right choice when you need centrally governed, shared worker capacity — not when every developer runs agents on a laptop.

Cursor-hosted cloud

Isolated VMs in Cursor infrastructure. Fastest path to async agents; code is cloned into Cursor-managed sandboxes.

Best for: Teams comfortable with Cursor-managed execution, rapid experimentation, low ops overhead.

My Machines

Individual developers register personal workstations as workers. Good for ad-hoc runs with local repo access.

Best for: Power users, personal workflows, proofs of concept before fleet investment.

Self-managed pool

Admins operate shared workers in your Kubernetes cluster, VMs, or Cloud Run. Service account auth; labels route work by team, repo, or environment.

Best for: Regulated industries, network-segmented repos, internal build caches, CI-like agent runners at scale.

↯ Decision criteria

Criterion Favor self-managed pool Favor Cursor-hosted
CriterionData residency & tool execution Favor self-managed poolPolicy requires code, builds, secrets, and terminal commands to stay in-network Favor Cursor-hostedPrivacy Mode + contractual controls are sufficient; no hard residency requirement
CriterionInternal system access Favor self-managed poolAgents need private package registries, internal APIs, VPN-only services, or large local caches Favor Cursor-hostedWork is limited to public repos and standard SaaS integrations
CriterionOperational model Favor self-managed poolPlatform team can operate worker fleets (K8s, autoscaling, image pipelines) Favor Cursor-hostedNo capacity to run and patch agent worker infrastructure
CriterionScale & concurrency Favor self-managed poolDozens to thousands of parallel workers; custom autoscaling via fleet management API Favor Cursor-hostedModerate async usage; default limits (10 workers/user, 50/team) are adequate
CriterionTime to value Favor self-managed pool4–8 week runway acceptable for infra + security review Favor Cursor-hostedNeed agents live within days of Phase 3 kickoff

1 Stakeholder alignment checklist

  • Document approved use cases — incident triage, scoped refactors, internal tooling; exclude unsupervised production deploys until runbooks mature
  • Security signs off on hybrid model: orchestration in Cursor cloud, tool execution in your environment
  • Platform team commits to worker image maintenance, patching, and on-call for pool health
  • Finance models pooled usage impact — agent runs consume Enterprise usage like IDE sessions
  • Executive sponsor approves phased rollout budget (infra + Solutions Architect engagement)
How self-hosted execution works

Workers open a long-lived outbound HTTPS connection to Cursor. The agent loop (inference and planning) runs in Cursor's cloud; tool calls execute locally on your workers. Repos, build caches, secrets, and terminal commands stay in your environment. Workers need egress only — no inbound ports or VPN tunnels. Session artifacts (screenshots, videos) upload to Cursor for PR and dashboard visibility.

Prerequisites

Readiness & Governance Foundation

Do not stand up a worker pool until Phase 1 controls are live. Self-hosted agents amplify value from existing governance — they do not replace it.

Enterprise plan Self-Hosted Cloud Agents feature enabled
Identity SSO enforced, SCIM provisioning, Directory Groups mapped
Security Privacy Mode, hooks, audit log streaming
Automation auth Service account API keys with rotation policy

1 Enterprise & dashboard settings Solutions Architect

  • Confirm Cursor Enterprise plan with Self-Hosted Cloud Agents enabled (contact Cursor for company-wide scale beyond default limits)
  • Team admin opens Dashboard → Cloud Agents → Self-Hosted and configures routing policy
  • Choose routing mode: Allow Self-Hosted Agents (opt-in per request) or Require Self-Hosted Agents (all runs route to your pool)
  • Restrict Cloud Agent creation to approved IdP groups (e.g. cursor-platform-admins, cursor-agent-pilot)
  • Apply Repository Blocklist for repos that must never be agent-accessible

2 Service accounts & API keys

Pool workers authenticate with service account API keys only. User, personal, team, and organization API keys cannot start pool workers.

  • Create a dedicated service account for the worker pool with repo scope limited to approved repositories
  • Store API keys in your secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager) — never in images or git
  • Define key rotation schedule and document revocation procedure in incident runbooks
  • Separate service accounts per environment (dev/staging/prod pools) for blast-radius containment

3 Network & compliance

  • Allow outbound HTTPS from workers to api2.cursor.sh, api2direct.cursor.sh, and downloads.cursor.com
  • Document data flow for security review: orchestration in Cursor cloud, execution local, artifacts uploaded for visibility
  • Enable audit log streaming to SIEM; correlate agent sessions with worker IDs from fleet API
  • Configure Enterprise hooks (team hooks + enterprise-managed hooks) for compliance workflows on pool workers
  • Walk through Trust Center with InfoSec — Privacy Mode remains required
Readiness exit criteria

SSO/SCIM live, self-hosted routing policy set in dashboard, service account keys issued and stored securely, network egress approved, approved use cases documented, and Cloud Agent creation restricted to pilot IdP groups.

Architecture

Pool Design & Infrastructure Options

Design pools around how your teams work — by repo, environment, hardware profile, or business unit. Start small; scale with the fleet management API once utilization patterns are known.

Kubernetes (recommended at scale)

Helm chart + operator manage WorkerDeployment resources. Rolling updates preserve busy workers; autoscaling via readyReplicas.

K8s deployment guide

Google Cloud Run Worker Pools

Managed containers with optional autoscaler polling the fleet management API for utilization-based scaling.

Cloud Run guide

VM / bare-metal fleet

Run agent worker --pool under systemd or your process manager. Good for fixed-capacity teams or GPU profiles.

Self-Hosted Pool docs

Custom autoscaling

Poll /v0/private-workers/summary and /v0/private-workers/pending-requests to scale capacity when users wait for workers.

Fleet management API

1 Worker image requirements

  • Install agent CLI (curl https://cursor.com/install -fsS | bash) and git on PATH
  • Pre-clone approved repositories with configured remotes; register multiple roots via repeatable --worker-dir (up to 20 paths)
  • Include build tools, package registry credentials, and internal CA certs your agents need
  • Size CPU/memory for expected workload — default 1 CPU / 2Gi is a boot baseline, not a production sizing
  • Run agent worker --pool debug --json preflight before promoting images to production pools

2 Pool naming, labels & routing

Use --pool-name to segment fleets (e.g. gpu, staging, platform). Worker labels (--label team=backend, --label env=production) control which sessions match which workers. Users select pools from the Cloud Agents dropdown or via Slack/GitHub/Linear triggers.

Pool pattern Example When to use
Pool patternDefault pool Exampledefault (no --pool-name) When to useGeneral-purpose pilot; gradual rollout before named pools
Pool patternEnvironment-scoped Example--pool-name staging When to useSeparate dev/staging/prod network boundaries and secrets
Pool patternTeam-scoped Example--label team=payments When to useRoute work to specialists with domain-specific tooling
Pool patternHardware-scoped Example--pool-name gpu When to useML repos, large builds, or accelerated compile farms

3 IdP group mapping for agent access

IdP group Cursor control Pool access
IdP groupcursor-platform-admins Cursor controlAdmin + pool operator Pool accessDeploy workers, view fleet dashboard, configure routing policy
IdP groupcursor-agent-pilot Cursor controlCloud Agent creation allowed Pool accessRun agents against default or staging pools
IdP groupcursor-all-engineering Cursor controlIDE access only (initially) Pool accessAgent access added after pilot metrics prove stable
Rollout

Phased Enablement & Rollout Plan

Treat pool rollout like any production platform change: pilot with platform admins, measure recovery metrics, then expand IdP groups and pool capacity in stages.

1 Phase A — Stand up pilot pool Solutions Architect

  • Deploy 3–5 workers in a non-production pool (K8s WorkerDeployment or manual agent worker --pool)
  • Authenticate workers with scoped service account key; verify workers appear in Dashboard → Cloud Agents → Self-Hosted
  • Set dashboard to Allow Self-Hosted Agents — users opt in per session during pilot
  • Platform admin runs 2+ end-to-end agent workflows (refactor, test fix, internal tooling) and documents runbooks
  • Validate hooks fire correctly on pool workers (project + team + enterprise-managed hooks)

2 Phase B — Pilot user group

  • Enable Cloud Agent creation for cursor-agent-pilot IdP group only
  • Champion-led enablement: how to select self-hosted pool in Cloud Agents dropdown, Slack triggers, and PR workflows
  • Monitor fleet utilization via /v0/private-workers/summary; tune readyReplicas or autoscaler thresholds
  • Track recovery metric: pilot group running 2+ documented Cloud Agent workflows with measurable outcomes
  • Review audit logs weekly with security — no policy drift or unapproved repo access

3 Phase C — Production scale

  • Promote to production pools with environment-specific images, labels, and service accounts
  • Switch to Require Self-Hosted Agents if policy mandates in-network execution for all async runs
  • Expand IdP groups incrementally — never enable org-wide agent creation before pilot metrics are green
  • Integrate Slack, GitHub, and Linear triggers with pool= and repo= labels for automation
  • Contact Cursor for company-wide deployments beyond default limits (10 workers/user, 50/team)

4 Rollout timeline

Weeks 1–2
Decision workshop · Security architecture review · Service account provisioning · Network egress approved
Weeks 3–4
Pilot pool deployed · Workers visible in dashboard · Platform admin runbooks validated · Allow Self-Hosted enabled
Weeks 5–6
Pilot IdP group enabled · Champion enablement · 2+ workflows documented · Fleet utilization baselined
Weeks 7+
Production pools · Autoscaling live · Incremental group expansion · Require Self-Hosted (if mandated) · ADM QBR metrics
Rollout exit criteria

Production pool operational with autoscaling, pilot workflows documented and repeatable, security sign-off on audit correlation, spend tracked in pooled usage dashboard, and expansion cohort approved by engineering leadership.

Operations

Ongoing Operations & Governance

A self-managed pool is a living platform. Budget for image updates, capacity planning, and quarterly security reassessment alongside your CI/CD runner fleet.

1 Monitoring & capacity

  • Dashboard weekly review: connected workers, idle vs. busy ratio, pending pool requests
  • Alert on /v0/private-workers/pending-requests queue depth — scale before users wait
  • Export /metrics from workers (via --management-addr) into your observability stack
  • Reconcile agent spend against pooled usage burn rate in monthly ADM reviews

2 Safe deployments

  • Use rolling updates (K8s operator or blue/green VM fleet) — busy workers are never terminated mid-session
  • Pin agent CLI versions in images; test in staging pool before production rollout
  • Rotate service account keys on schedule; Kubernetes controller can manage short-lived token mounts
  • Maintain runbooks for worker disconnects, auth failures, and repo clone drift

3 Governance rhythm

  • Quarterly: review approved use cases, repo blocklist, and IdP group assignments
  • Quarterly: audit hooks coverage and enterprise-managed hook distribution to pool workers
  • Annual: security reassessment with Trust Center updates and incident response drill
  • On champion turnover: update enablement materials and internal Slack/runbook links
If rollout stalls

See the Cloud Agents blocked or stalled play in Risk Mitigation Plays. Common blockers: security freeze, missing architecture review, or pilot group without documented workflows. Escalate to your Solutions Architect for a joint session with InfoSec and platform engineering.

Resources & Documentation

Official Cursor references for pool design, deployment, and fleet management.