Last checked: 21 Oct 2026. Every vendor fact below comes from Cursor's own pages: the TypeScript and Python SDK docs, the cloud agent, automations, security and pricing documentation, Cursor's blog and changelog, and its published terms.
The Cursor SDK lets your own code start and steer Cursor's coding agent. You need it when your software decides when an agent runs, for which user or thread, and what happens to the result. If a schedule, a pull request, a Slack message or a webhook is enough to start the job, a Cursor automation or the headless CLI may already do it, with less for you to build and maintain.
Cursor's pages now link to SpaceX Super Intelligence (SpaceXSI) subscription terms, and Cursor's blog says it was acquired by SpaceX on 14 Aug 2026. Our guide to SpaceXSI for UK business covers the wider product set.
What the Cursor SDK is
The TypeScript package, @cursor/sdk, lets you "call Cursor's agent from your own code" and needs Node.js 22.13 or later (TypeScript docs). The Python package, cursor-sdk, needs Python 3.10 or later (Python docs). Other languages go through the SDK Bridge, and Cursor says adapters built on it are not first-party: whoever builds one owns its versioning, support and security review.
Cursor's launch post of 29 Apr 2026 says the SDK uses the same runtime, harness and models that power Cursor, and that it launched in public beta for all users (the changelog agrees). The current docs carry no beta label, so check the status on the day you start, and read the release notes, which are undated and show frequent change.
The docs describe it as an agent SDK, "not a standalone model-inference or chat-completions API". Cursor also publishes a cookbook repository of small examples. We did not see a licence named on it, so check before copying code into a product.
Do you need the SDK, or will an automation do?
Three Cursor routes run an agent without someone at the editor. Cursor's pages do not compare them, so this table is ours.
| Route | What starts the agent | Fits when |
|---|---|---|
| Cursor Automations | A schedule, or events from GitHub, GitLab, Slack, webhooks, Linear, Sentry or PagerDuty | The trigger is an event Cursor already listens for and the job is the same each time |
| Headless CLI | A script or CI step | A pipeline step needs analysis or a proposed change, and nothing tracks state between runs |
| Cursor SDK | Your own code | Your software decides when to run and for whom, keeps state across runs, or shows the work inside your own interface |
Automations bill as cloud agent usage and run as their own service account. Pull request triggers do not run on forks and Slack triggers see only public channels. The headless CLI only proposes changes unless you pass a force flag.
A practical test: write down what starts the job and where the result goes. If the answer is "a pull request opens and a comment comes back", an automation is probably enough, and our post on what to automate first with Cursor covers that path. If it involves a user in your product, a conversation that continues over days, or your own approval step, you are describing an SDK build.
The two uses, and why they are different purchases
Cursor's launch post names agents kicked off from CI/CD, internal applications such as tools that let GTM teams query product data, and "embedding Cursor directly into customer-facing products". For a buyer, those fall into two groups. The commercial difference between them is our analysis, not something Cursor publishes.
Agents for your own engineering
This covers CI checks that fix a failing build, bug triage workers, review passes on pull requests and small internal tools. The users are your staff and the bill sits with your team. SDK runs follow the same pricing, request pools and Privacy Mode rules as the editor and cloud agents, billed on token-based consumption. Service account keys bill to the owning team, user keys bill to that user's plan, and spend shows in the team usage dashboard under an SDK tag (Python docs).
Service accounts are an Enterprise feature. They take no seat, draw on the team pool and have no spend limit until an admin sets one (service accounts docs). Our reading: without Enterprise, SDK jobs run on a person's key, which ties the job to that person and bills their plan.
Agents inside a product you sell
Here every customer may cause an agent to run. The engineering is similar, but the commercial questions are new.
- Terms. Cursor's Online Terms (updated 3 Sep 2026) and Master Services Agreement (updated 12 Oct 2026) contain no SDK or embedding clause. The Online Terms bar customers from renting, leasing, lending or selling the Service. Where you have an MSA it governs, and an Order Form takes priority over it. The public terms do not set out how Cursor can be built into a product you sell, so agree that with Cursor in writing before you build.
- Paperwork in transition. Cursor's pricing help says Cursor is now sold inside a combined subscription with Grok and X, and legacy plans are closed to new customers, while the data processing addendum is still dated 5 Nov 2025. Confirm which documents apply to you.
- Who pays per customer. If agents run on your keys, every customer's usage lands on your bill, so you need your own per-customer metering and limits. Cursor's separate Notion integration for end users bills each user's own Cursor account through their personal API key, which shows that a bring-your-own-account design is possible. That is our observation, not how any SDK customer is billed.
Local runs and cloud runs
You choose a runtime when you create an agent. A local run "runs the agent loop inline in your Node process", with files read from disk. A cloud run happens "in an isolated VM with your repo cloned in", on machines Cursor runs (TypeScript docs). Cursor suggests cloud when the caller does not have the repository, when you want many agents in parallel, or when runs must survive the caller disconnecting.
"Local" does not mean the model is local: the docs say all inference goes through Cursor's hosted models in both modes.
Cloud agents clone from GitHub, GitLab, Azure DevOps Services or Bitbucket Cloud, work on a separate branch and can open pull requests. They need read-write access to the repository and any dependent repositories (cloud agent docs). They are also the one Cursor feature that stores your code: on machine disks on AWS while the agent is accessible. Conversation history is kept indefinitely by default, and environment snapshots are kept for up to 30 days of inactivity and cannot be deleted on demand. Enterprise admins can set conversation retention to 90 days (security and network docs). Cursor's privacy and data governance page says stored repository copies are deleted after the agent completes, so read it alongside the snapshot rule. It offers US-only residency to Enterprise customers and EU and UK inference-only coverage on request, with no UK storage option.
Self-hosted workers keep the checkout, build cache and local credentials on your machine, but Cursor still runs the agent loop, inference and planning, and receives the content the agent needs (self-hosted docs). The launch post says the SDK can use self-hosted workers, but the self-hosted docs describe no SDK setting, so confirm it with Cursor. See self-hosted Cursor agents for more.
How an agent's lifecycle works
In the TypeScript docs, an agent is a durable container for conversation state across prompts, and a run is one prompt submission. There are three ways to start:
Agent.prompt()creates an agent, sends one prompt, waits for the run and disposes of the agent. It suits a CI step.Agent.create()returns a handle straight away, and the agent takes further prompts as separate runs. The docs say to always dispose of agents when done.Agent.resume()reattaches by ID. Inline MCP server settings (how an agent reaches outside tools and data) are not kept across a resume because they often carry secrets, so supply them again.
Only one run can be active per agent. A second run sent during an active one gets an agent busy error, and retrying immediately keeps failing until the active run ends or is cancelled (Cloud Agents API docs). Our inference: where one conversation maps to one agent, follow-up messages must queue. A run ends as finished, error or cancelled (Python adds expired). For a service that owns many agents, the docs describe a dispatcher pattern, where "a dispatcher owns a pool of agents and hands work to them as it arrives".
What goes wrong
An unattended local agent with no limits. Fix this first. A local SDK agent runs headless with no human approval prompt, and its sandbox is off by default (TypeScript docs). Hooks can only be set in files. Tool allowlists and denylists exist, and the deny wins. Cursor's optional auto-review classifier is, in its words, "not a security boundary". Turn on the sandbox, hooks or tool limits before anything runs unattended, and put the agent through a pre-ship security review.
Two kinds of failure. In the documented examples, problems setting up or submitting a run are thrown as errors, and a run that executes and fails reports an error status on its result. Handle both. Thrown errors share a base class and carry a retry flag, a code, a status and a request ID. Listed causes include a bad key, a burst limit or monthly usage cap, a busy agent, a source control provider not connected to the Cursor team, and transient network errors. Drive retries from the retry flag and log the request ID.
Agents nobody can see. Cloud agents started by the SDK are filtered out of the default list in Cursor Web, and only appear under Filter, Source, SDK. You can attach your own string tags when you create one.
Beta interfaces and silent settings. The Cloud Agents API v1 behind cloud runs is in public beta and may change. Webhooks are listed as coming soon. A reconnecting stream may be refused after a retention window the page does not state. An environment variable field is silently ignored if the feature is not enabled for your account.
Timers you cannot plan around. Idle machines are hibernated and then deleted on timers the cloud agent security page does not publish. If your product resumes long-idle threads, ask Cursor.
How Notion built on it
Cursor's blog describes how Notion used the Cursor SDK to embed coding agents (25 Jun 2026). By Cursor's account, a Notion thread becomes a Cursor agent and every message becomes a run. Output streams over server-sent events, and a user can resume from the last event if a connection drops. The SDK connects agents to Notion's own remote MCP server so they can read and write the workspace. A Notion engineer quoted in the post calls the integration "a thin adapter".
The useful detail is that Notion put Cursor behind a provider-agnostic harness for external agents, with Cursor as one implementation. That keeps the agent engine swappable. The post gives no figures on cost, adoption or reliability, so treat it as an account of architecture only.
A reference architecture your platform team can own
These components come from the documented parts above. The structure is our recommendation.
- One dispatcher service. It creates, resumes and disposes of agents, and stores each agent ID against its user, thread or job. Nothing else calls the SDK directly.
- A queue per agent. Messages wait until the previous run reaches a final status, so a busy agent is a queue state rather than an error.
- Service account keys for production. On Enterprise, run production jobs on a service account with a spend limit set from day one. Keep personal keys for experiments.
- Your own run log and usage meter. Tag every cloud agent and record agent ID, requester, status, error code and request ID, since the Cursor Web list hides SDK agents. In a product, meter usage per customer.
- Limits on local runs. Sandbox on, hooks set in files, and the narrowest tool list that does the job.
- Secrets and network scope on cloud runs. Cloud agents can be limited to a domain allowlist, and secrets set as environment variables are visible to the agent (security docs). Our post on Cursor cloud agent security goes further.
- A written retention decision. Indefinite or 90-day conversations, noting that snapshots persist for up to 30 days of inactivity regardless.
- A plan for change. Pin the SDK version, read release notes before upgrading, and wrap the SDK behind your own interface, as Notion did, so a beta change touches one adapter.
On cost, Cursor's pages describe cloud agents in two ways: the cloud agent docs say they are charged at API pricing for the selected model, while the models and pricing page describes one usage pool per paid plan shared across products, with third-party models outside it. Check the current pricing page, and expect the model you choose to move the cost.
We use Cursor in our own engineering. In an SDK project most of the work sits in the dispatcher, queue, logging and limits, which your platform team will maintain. The ownership questions are the same ones we cover for another vendor in build in-house or hire it out.
Common questions
What is the Cursor SDK?
It is a set of TypeScript and Python packages that let your own code call Cursor's coding agent, using the same runtime, harness and models as Cursor itself. It is an agent SDK rather than a general model API. Cursor launched it in public beta on 29 Apr 2026, so check its current status before you build.
Do we need the Cursor SDK, or is a Cursor automation enough?
Cursor Automations start cloud agents from a schedule or from events in tools such as GitHub, GitLab, Slack, Linear, Sentry and PagerDuty, or from a webhook. If one of those starts the job and the result goes back to the same place, an automation is probably enough. You need the SDK when your own code decides when an agent runs and has to track state per user, thread or job.
Does the Cursor SDK run locally, and where does our code go?
You choose. A local run keeps the agent loop and file access in your own process, but inference still goes through Cursor's hosted models. A cloud run clones your repository into an isolated machine that Cursor runs, and the code is stored on that machine's disk while the agent is accessible. Environment snapshots are kept for up to 30 days of inactivity.
How is Cursor SDK use billed?
On token-based consumption, under the same pricing, request pools and Privacy Mode rules as the editor and cloud agents. Service account keys bill to the owning team and user keys bill to that user's plan. Cursor's pages describe cloud agent cost in two ways, so check the current pricing page.
Can we build Cursor into a product we sell?
Cursor names embedding in customer-facing products as a use of the SDK and features Notion as an example. Its public terms do not set out how that works commercially, so agree the position with Cursor in writing before you build.
If you want to know whether your use case needs an SDK build or an automation, start with a diagnostic, or visit our SpaceXSI implementation page to Request a Quote.
John Kelleher holds the SpaceX Super Intelligence Partner Network Accreditation: Forward Deployed Engineer.
Get new articles by email
Practical guides from the SpotDev team, when we publish them.
By submitting this form, you consent to us sending you emails with our latest content. Privacy Policy
