{"id":817,"date":"2026-04-30T12:40:37","date_gmt":"2026-04-30T04:40:37","guid":{"rendered":"https:\/\/connectword.dpdns.org\/?p=817"},"modified":"2026-04-30T12:40:37","modified_gmt":"2026-04-30T04:40:37","slug":"cursor-introduces-a-typescript-sdk-for-building-programmatic-coding-agents-with-sandboxed-cloud-vms-subagents-hooks-and-token-based-pricing","status":"publish","type":"post","link":"https:\/\/connectword.dpdns.org\/?p=817","title":{"rendered":"Cursor Introduces a TypeScript SDK for Building Programmatic Coding Agents With Sandboxed Cloud VMs, Subagents, Hooks, and Token-Based Pricing"},"content":{"rendered":"

Cursor, the AI-powered code editor, is opening up the core technology behind its coding agents to developers everywhere. The Cursor team announced the public beta of the Cursor SDK<\/strong> \u2014 a TypeScript library that gives engineers programmatic access to the same runtime, harness, and models that power Cursor\u2019s desktop app, CLI, and web interface.<\/p>\n

This signals a meaningful shift in how AI coding tools are being positioned: not just as interactive assistants sitting alongside a developer, but as deployable infrastructure that organizations can wire into their existing systems.<\/p>\n

From Interactive Tool to Programmable Infrastructure<\/strong><\/h3>\n

If you\u2019ve used Cursor before, you know it as an IDE where you interact with an agent in real time \u2014 asking it to write functions, fix bugs, or explain code. The Cursor SDK changes the access model. Instead of a developer sitting at a keyboard, the agent can now be invoked programmatically: from a CI\/CD pipeline trigger, a backend service, or embedded directly inside another product.<\/p>\n

Think of it this way: previously, you had to be \u201cin\u201d Cursor to use its agents. Now, you can call those same agents from anywhere in your stack with a few lines of TypeScript.<\/p>\n

Getting started is a single command:<\/strong><\/p>\n

\n
\n
\n
\n
<\/div>\n
<\/div>\n
<\/div>\n<\/div>\n
Copy Code<\/span>Copied<\/span>Use a different Browser<\/span><\/a><\/div>\n<\/div>\n
npm install @cursor\/sdk<\/code><\/pre>\n<\/div>\n<\/div>\n
From there, you create an Agent<\/code> instance, send it a task, and stream the response back \u2014 all in TypeScript. Here\u2019s the minimal example from Cursor\u2019s announcement:<\/p>\n
\n
\n
\n
\n
<\/div>\n
<\/div>\n
<\/div>\n<\/div>\n
Copy Code<\/span>Copied<\/span>Use a different Browser<\/span><\/a><\/div>\n<\/div>\n
import { Agent } from \"@cursor\/sdk\";\n\nconst agent = await Agent.create({\n  apiKey: process.env.CURSOR_API_KEY!,\n  model: { id: \"composer-2\" },\n  local: { cwd: process.cwd() },\n});\n\nconst run = await agent.send(\"Summarize what this repository does\");\n\nfor await (const event of run.stream()) {\n  console.log(event);\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
The Agent.create()<\/code> call accepts an apiKey<\/code>, a model<\/code> field (where you specify which model to run), and either a local<\/code> or cloud<\/code> configuration depending on where you want execution to happen.<\/p>\n
Why Building Your Own Agent Stack is Hard<\/strong><\/h3>\n
Before diving into what the SDK offers, it\u2019s worth understanding the problem it solves. Building fast, reliable, and capable coding agents that run safely against your data requires meaningful engineering effort: secure sandboxing, durable state and session management, environment setup, and context management. And when a new model ships, dev teams often have to rework their agent loops entirely just to take advantage of it. The Cursor SDK eliminates this complexity so teams can focus on building useful agents instead of maintaining the underlying infrastructure.<\/p>\n
https:\/\/cursor.com\/blog\/typescript-sdk<\/figcaption><\/figure>\n
The Agent Harness: What \u201cSame Runtime\u201d Actually Means<\/strong><\/h3>\n
SDK agents use the same harness that powers Cursor\u2019s own products. \u2018Harness\u2019 here refers to the full set of supporting infrastructure that makes an agent effective beyond just the LLM call itself. In Cursor\u2019s case, that includes:<\/strong><\/p>\n
Intelligent context management<\/strong> \u2014 Codebase indexing, semantic search, and instant grep so agents retrieve the right code context before generating responses. This is critical because LLMs are only as good as the context they receive; poor retrieval leads to hallucinated or irrelevant outputs.<\/p>\n
MCP servers<\/strong> \u2014 Agents launched through the SDK can connect to external tools and data sources over stdio<\/code> or HTTP, either via a .cursor\/mcp.json<\/code> config file or passed inline in the API call. MCP (Model Context Protocol) is an open standard for wiring tools into agent runtimes.<\/p>\n
Skills<\/strong> \u2014 Agents automatically pick up reusable behavior definitions from a .cursor\/skills\/<\/code> directory in the repository.<\/p>\n
Hooks<\/strong> \u2014 A .cursor\/hooks.json<\/code> file lets you observe, control, and extend the agent loop across cloud, self-hosted, and local runtimes \u2014 useful for logging, guardrails, or custom orchestration.<\/p>\n
Subagents<\/strong> \u2014 The main agent can delegate subtasks to named subagents with their own prompts and models via the Agent<\/code> tool, enabling multi-agent workflows without custom orchestration code.<\/p>\n
Cloud Deployment: Persistent, Sandboxed, and Resumable<\/strong><\/h3>\n
One of the more practical features of the SDK is cloud execution. When configured to run in Cursor\u2019s cloud, each agent gets its own dedicated VM with strong sandboxing, a clone of the target repository, and a fully configured development environment. Critically, the agent keeps running even if the initiating machine goes offline \u2014 the developer can reconnect and stream the conversation later.<\/p>\n
Cloud agents integrate with Cursor\u2019s existing Agents Window and web app, so a task started programmatically via the SDK can be inspected or taken over manually inside the Cursor interface. When the agent finishes, it can open a PR, push a branch, or attach demos and screenshots \u2014 making them suitable for asynchronous, unattended workflows:<\/p>\n
\n
\n
\n
\n
<\/div>\n
<\/div>\n
<\/div>\n<\/div>\n
Copy Code<\/span>Copied<\/span>Use a different Browser<\/span><\/a><\/div>\n<\/div>\n
const agent = await Agent.create({\n  apiKey: process.env.CURSOR_API_KEY!,\n  model: { id: \"gpt-5.5\" },\n  cloud: {\n    repos: [{ url: \"https:\/\/github.com\/cursor\/cookbook\", startingRef: \"main\" }],\n    autoCreatePR: true,\n  },\n});\n\nconst run = await agent.send(\"Fix the auth token expiry bug\");\nconsole.log(`Started ${run.id}`);\n\n\/\/ ...check back in later, from anywhere:\nconst result = await (\n  await Agent.getRun(run.id, { runtime: \"cloud\", agentId: run.agentId })\n).wait();\nconsole.log(result.git?.branches[0]?.prUrl);\n<\/code><\/pre>\n<\/div>\n<\/div>\n
For dev teams with security requirements, the SDK also supports self-hosted workers, where both code and tool execution remain inside the organization\u2019s own network.<\/p>\n
Model Flexibility and Composer 2<\/strong><\/h3>\n
The SDK exposes every model supported in Cursor. Switching models is a single field change in the model<\/code> parameter, letting teams route tasks to the best model for a given combination of cost and capability. Cursor\u2019s own Composer 2<\/strong> \u2014 described as a specialized coding model achieving frontier-level performance at a fraction of the cost of general-purpose models \u2014 is positioned as the default recommendation for most coding agent tasks.<\/p>\n
Getting Started<\/strong><\/h3>\n
To accelerate adoption, Cursor has published a public cookbook repository<\/a> on GitHub with four starter projects: a minimal quickstart (a Node.js example that creates a local agent, sends one prompt, and streams the response), a web-based prototyping tool for scaffolding new projects in a sandboxed cloud environment, an agent-powered kanban board that automatically opens PRs when engineers drag a card, and a lightweight coding agent CLI for spawning Cursor agents from the terminal.<\/p>\n
Cursor has also released a Cursor SDK plugin<\/strong> in the Cursor Marketplace to help developers start building directly from within the editor.<\/p>\n
Key Takeaways<\/strong><\/h3>\n