{"slug": "build-cursor-cloud-agents-12-steps-90-min-2026", "title": "Build Cursor Cloud Agents: 12 Steps, 90 Min [2026]", "summary": "Cursor released a public beta of its Environments API on October 16, 2026, letting developers create and manage the cloud environments that Cloud Agents run in through REST calls rather than the Cursor dashboard, with each environment built from a repository plus its environment.json configuration. The same release raised the repository ceiling on a single environment to 300, cut load times for large environments by a reported 5x, and added Cloud Agent Canvases that agents build as shareable interactive output; it followed remote control for local agents on October 6 and the Origin App Marketplace on October 13. Cursor's case study reports roughly 200 engineers at travel-management company Navan now use Cloud Agents, a 10x increase since April 2026, with one team cutting a month-long migration across eight applications to about a week.", "body_md": "Cursor shipped three updates inside eleven days this October: remote control for local agents on October 6, the Origin App Marketplace on October 13, and Cloud Agent Canvases paired with a beta Environments API on October 16, 2026. Taken together, they turn Cursor’s Cloud Agents from a single remote coding assistant into something closer to a programmable fleet. You can now spin up an isolated cloud environment through a REST API, point it at up to 300 repositories, run an agent against it, and get back a shareable interactive result instead of a wall of text.\n\nThis matters because agent adoption has moved past the experimentation phase. Stack Overflow’s [2025 Developer Survey](https://stackoverflow.co/company/press/archive/stack-overflow-2025-developer-survey/) found that “31% of developers currently use AI agents,” and separately reported that “18% of developers regularly use Cursor” specifically. Gartner projects the shift will keep accelerating: in its 2025 strategic trends release, the firm forecast that [“by 2028, 90% of enterprise software engineers will use AI code assistants, up from less than 14% in early 2024.”](https://www.gartner.com/en/newsroom/press-releases/2025-07-01-gartner-identifies-the-top-strategic-trends-in-software-engineering-for-2025-and-beyond) An API that lets you manage cloud environments programmatically, rather than clicking through a dashboard every time, is exactly the kind of plumbing that adoption curve demands.\n\nThis tutorial builds a working Cloud Agent pipeline from scratch: installing the CLI, creating an environment through the new Environments API, configuring it, launching and streaming an agent run, scaling it to a multi-repository setup, sharing the result as a canvas, and wiring in the monitoring bots Cursor introduced alongside it. Twelve steps, one complete project, and a troubleshooting section built from real issues reported on Cursor’s own community forum in the weeks since launch.\n\nDon't miss new tech stories on Google\n\nAdd Shattered once in the Google app and our stories show up in your news suggestions.\n\n[Add now](https://www.google.com/preferences/source?hl=en&q=https%3A%2F%2Fshattered.io%2F)\n\n## What Changed on October 16: Cloud Agent Canvases and the Environments API\n\nBefore this release, Cloud Agents already ran on their own remote machines, building, testing, and demonstrating software without tying up a developer’s laptop. What changed is how much of that process you can now control through code instead of the Cursor dashboard. The Environments API entered public beta on October 16, 2026, letting developers programmatically create and manage the cloud environments that agents run in, each one built from a repository plus its `environment.json` configuration. The same release raised the repository ceiling on a single environment to 300 and cut load times for large environments by a reported 5x.\n\nCloud Agents also stopped being a text-only tool. As of October 16, agents can build interactive canvases as part of their output and you can share a finished canvas with a teammate by sending its link, no screen recording or copy-pasted diff required. Cursor’s own case study on the release describes roughly 200 engineers at travel-management company Navan now actively using Cloud Agents, which the company called a 10x increase in usage since April 2026, with one team using agents to carry a month-long migration across eight applications down to about a week.\n\nCursor isn’t alone in building toward this kind of programmable agent infrastructure. OpenAI published its own [Agents API](https://openai.com/index/introducing-the-agents-api/) to let developers orchestrate multi-step agent workflows outside of a chat window, and terminal-focused competitor Warp documents a comparable concept of cloud agent environments for isolating agent runs from a developer’s machine. The pattern across all three: move agent execution off the laptop and into a reproducible, API-managed environment that a team can share, audit, and scale.\n\nWhat pushed Cursor to build a REST API around this rather than leaving it as a dashboard-only feature is the same thing that pushes most developer tools toward an API eventually: a single engineer clicking through a web UI doesn’t scale to an organization running agents as a routine part of its CI pipeline. The Navan case study is a useful proof point here precisely because it’s an adoption number, not a feature announcement, going from one engineer experimenting with Cloud Agents in April 2026 to roughly 200 people using them regularly by October, a pattern that only works once the setup, launch, and monitoring steps can be scripted instead of repeated by hand.\n\n| Capability | Before October 16, 2026 | After October 16, 2026 | \n|---|---|---|\n| Environment creation | Dashboard only | Programmatic via Environments API (beta) | \n| Repositories per environment | Lower, undocumented cap | Up to 300 repositories | \n| Large environment load time | Baseline | Reported 5x faster | \n| Agent output format | Text, diffs, and PRs | Adds interactive, shareable canvases | \n| Starting a run from a commit | Full 40-character hash or branch name | Short commit ID, auto-resolved | \n| Environment builds | Optional toggle | Automatic for non-draft environments | \n\n## Cloud Agents vs Local Agents vs Remote Control: Choosing the Right Mode\n\nBefore writing any code, it’s worth being clear on which of Cursor’s three execution modes actually fits the task in front of you, since the terminology gets confusing fast once Remote Control enters the picture. A local agent runs directly on your own machine inside the Cursor desktop app, with full access to whatever is already checked out and running there. A Cloud Agent runs somewhere else entirely: an isolated cloud virtual machine built from one of the environments this tutorial walks through creating. Remote Control doesn’t replace either of those, it’s a thin layer that lets you watch and reply to a local agent from your phone while it keeps running on your own, still-awake machine.\n\nGetting this wrong wastes time in both directions. Sending a quick, five-minute fix to a Cloud Agent means waiting on environment startup for a task that would have finished locally before the cloud machine even booted. Running a long, multi-repository migration as a local agent ties up your laptop for however long that migration takes, and loses it entirely if you close the lid. The table below is the rule of thumb to default to.\n\n| Mode | Where it runs | Best for | What you need | \n|---|---|---|---|\n| Local agent (in-editor) | Your own machine, via the Cursor desktop app | Fast iteration on small changes with full local file-system access | The Cursor desktop app | \n| Local agent + Remote Control | Your own machine, monitored from your phone | Letting a local agent keep working while you step away from your desk | Cursor iOS app paired to your account, host machine kept awake | \n| Cloud Agent | An isolated cloud VM built from an environment | Long-running or multi-repository tasks you don’t want tying up your laptop | On-demand billing enabled, an environment created via the API or dashboard | \n| Cloud Agent + Canvas | Same isolated cloud VM | Sharing a finished result with teammates who don’t have API or editor access | Nothing extra, canvases are produced automatically when the task calls for one | \n\nThis tutorial focuses on the bottom two rows, since that’s where the Environments API and the October 16 release live, but Step 10 covers Remote Control separately for the cases where a local agent is still the right call.\n\n## Prerequisites and Versions You’ll Need\n\nYou don’t need a desktop install of Cursor to follow this tutorial, since everything here runs through the Cloud Agents API and the Cursor CLI, but having the editor open makes it easier to review diffs and canvases as they come back. Here’s what to line up first.\n\n- A Cursor account with a plan that includes Cloud Agent access. Cursor’s current pricing page lists three paid tiers above the entry level: Premium at $30/month ($300/year), recommended for new AI users, Super at $100/month ($1,000/year), recommended for daily agent users, and Ultra at $200/month ($2,000/year). An $8/month Plus tier exists too, but it covers Grok-only models rather than the full Cursor model lineup.\n- A repository hosted on GitHub, GitLab, Bitbucket Cloud, or Azure DevOps. The Cloud Agents API v1 supports all four for repository-backed environments and runs.\n- The Cursor CLI installed locally, and a terminal comfortable with `curl` or a scripting language (this tutorial uses bash and a short Node.js snippet).\n- A Cursor API key with on-demand billing enabled and a spending limit set. Cloud Agents require both before your first agent launches, even if you have included plan usage left.\n- Fifteen minutes free for the first run, and closer to ninety if you work through the multi-repository and canvas-sharing steps as well.\n\nIf you’ve never designed a REST API from scratch before, it’s worth practicing against a simpler, well-documented dataset first, since that makes it much easier to read unfamiliar endpoints like the ones you’re about to call. We walked through that exact exercise in a tutorial that turns a game’s full season history into a queryable [FastAPI-backed service](https://shattered.io/fortnite-season-database-api-2026/), and the same request and response patterns apply directly to what follows here.\n\n## Step 1: Install the Cursor CLI and Confirm Your Version\n\nStart by getting the CLI onto your machine. It handles authentication, environment scaffolding, and several of the shortcuts used later in this tutorial.\n\n```\ncurl https://cursor.com/install -fsS | bash\ncursor-agent --version\ncursor-agent login\n```\n\nThe `login` command opens a browser window to authenticate your CLI session against your Cursor account. Once it completes, the terminal prints a confirmation and the CLI is ready to issue API calls under your account’s identity. If your organization uses SSO through a Teams or Enterprise plan, this is also the point where that policy gets enforced, so have your admin confirm CLI access is allowed before you spend time debugging an auth failure that’s actually a permissions setting.\n\nKeep the CLI updated as you work through the rest of this tutorial. Several of the fixes referenced later, the improved `environment.json` parser and the friendlier error messages in particular, only apply once you’re running a build current enough to include them, and an outdated CLI is one of the more common reasons a step that should work exactly as written instead throws an unfamiliar error.\n\n## Step 2: Generate a Scoped API Key and Set a Spending Limit\n\nCloud Agents bill against the selected model’s standard API rate, drawing from included plan usage first and falling back to on-demand usage at the same rate once that’s exhausted. Cursor requires on-demand billing to be switched on, and a spending limit set, before you can launch your first Cloud Agent at all. Do this from your account’s billing settings, then export the resulting API key as an environment variable so none of the commands below need it typed in plain text.\n\n```\nexport CURSOR_API_KEY=\"YOUR_API_KEY\"\ncurl --request GET \\\n  --url 'https://api.cursor.com/v1/environments' \\\n  -u $CURSOR_API_KEY:\n```\n\nA fresh account returns an empty list at this point, which is expected. Note the trailing colon after the key in the `-u` flag: Cursor’s API authenticates with basic auth where the key is the username and the password field is left blank.\n\n## Step 3: Create Your First Environment with the Environments API\n\nAn environment, in Cursor’s model, is a saved Cloud Agent configuration built from a repository plus its `environment.json` file. Creating one programmatically is the headline feature of the October 16 beta release, and it’s what lets you treat environment setup as code instead of a one-off dashboard task.\n\n```\ncurl --request POST \\\n  --url 'https://api.cursor.com/v1/environments' \\\n  -u $CURSOR_API_KEY: \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"name\": \"migration-demo\",\n    \"repository\": \"github.com/your-org/your-repo\"\n  }'\n```\n\nThe response returns an environment ID you’ll reuse in every step that follows. Treat it the way you’d treat a cloud resource ID from any other provider: store it in your pipeline’s configuration rather than hardcoding it into scripts, since you’ll likely create more than one environment as your usage grows past a single demo repository.\n\n## Step 4: Write environment.json for Your Repository\n\nEvery environment is defined by the repository you pointed it at plus a configuration file that tells Cursor how to build and start your project. Keep this file in your repository root, and keep it simple at first: the fewer assumptions it makes, the easier it is to debug when a build fails. A minimal version looks like this, adjusted to match your own project’s actual install and start commands.\n\n```\n{\n  \"install\": \"npm install\",\n  \"start\": \"npm run dev\",\n  \"terminals\": [\n    { \"name\": \"logs\", \"command\": \"npm run logs\" }\n  ]\n}\n```\n\nAs of October 20, 2026, Cursor’s environment file parser accepts comments and trailing commas, and an invalid file now returns a syntax error that identifies where parsing stopped, which is a meaningful improvement if you’ve ever had to guess which line of a config file was wrong from a generic failure message. Commit this file alongside your code so it stays versioned with the rest of your repository instead of living only inside Cursor’s dashboard.\n\n## Step 5: Trigger and Verify an Environment Build\n\nNon-draft environments build automatically now, and builds can no longer be turned off, a deliberate change that ensures every new Cloud Agent starts from a fresh, working build rather than a stale one. You can still check build status and history directly through the API, which is useful both for debugging and for feeding build metadata into your own CI dashboards.\n\n```\ncurl --request GET \\\n  --url 'https://api.cursor.com/v1/environments/8f14e45f-ceea-4e6b-9c3a-1d2e3f4a5b6c/builds?createdAfter=2026-09-29T00:00:00Z&limit=2' \\\n  -u $CURSOR_API_KEY:\n```\n\nSwap in your own environment ID from Step 3. The `createdAfter` parameter expects an ISO 8601 timestamp with a `Z` suffix or UTC offset, at millisecond precision at most, so a value like `2026-09-29T00:00:00Z` is valid while a bare date string is not. If a build shows a warning rather than a hard failure, read it before moving on: Cursor’s environment builds now surface warnings for issues that won’t necessarily block an agent from starting but will likely cause it to misbehave once it does.\n\n## Step 6: Launch Your First Cloud Agent\n\nWith an environment built, launching an agent against it is a single call. The Cloud Agents API v1 supports durable, longer-running agents as well as individual prompt-scoped runs, and this example kicks off the simpler of the two: a scoped run tied to a specific prompt.\n\n```\ncurl --request POST \\\n  --url 'https://api.cursor.com/v1/agents' \\\n  -u $CURSOR_API_KEY: \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"environmentId\": \"8f14e45f-ceea-4e6b-9c3a-1d2e3f4a5b6c\",\n    \"prompt\": \"Add input validation to the signup form and open a PR.\"\n  }'\n```\n\nA successful call returns a run object similar to this while the agent is still starting up:\n\n```\n{\n  \"run\": {\n    \"id\": \"run-00000000-0000-0000-0000-000000000002\",\n    \"agentId\": \"bc-00000000-0000-0000-0000-000000000001\",\n    \"status\": \"CREATING\",\n    \"createdAt\": \"2026-04-13T18:50:00.000Z\",\n    \"updatedAt\": \"2026-04-13T18:50:00.000Z\"\n  }\n}\n```\n\nThe `status` field transitions as the run progresses, and it’s the field you’ll poll, or better, stream, to know when the agent has moved from setting up its sandbox to actually working on your prompt.\n\n## Step 7: Stream Agent Output and Send Follow-Ups\n\nPolling a status endpoint in a loop works, but it’s wasteful and slow to react to. The Cursor SDK, in public beta since April 29, 2026, was reworked specifically around durable agents and per-prompt runs, adding server-sent-event streaming, reconnection handling, and standardized response and error formats. A short Node.js example makes the difference clear.\n\n``` python\nimport Cursor from \"@cursor/sdk\";\n\nconst client = new Cursor({ apiKey: process.env.CURSOR_API_KEY });\n\nconst stream = client.agents.runs.stream(\"run-00000000-0000-0000-0000-000000000002\");\n\nfor await (const event of stream) {\n  console.log(event.type, event.data);\n  if (event.type === \"run.completed\") break;\n}\n```\n\nIf the agent gets close but misses a requirement, you can send a follow-up message scoped to that same run rather than starting over, which keeps the full context of its prior work intact. One caveat worth knowing before you rely on it in production: on cloud runs, a mid-run steering call reportedly falls back to behaving like an ordinary follow-up message rather than the same live steering behavior available through the local TypeScript SDK, according to forum reports from mid-October 2026. Design your prompts assuming cloud steering is a follow-up, not a live interrupt, until Cursor documents otherwise.\n\n## Step 8: Scale to a 300-Repository Environment\n\nThe repository ceiling increase is the part of this release that matters most for larger engineering orgs. Where a single environment previously covered a handful of repositories at most, the October 16 update raised that limit to 300, with large environments reported to load roughly 5 times faster than before. That’s the difference between an agent that can refactor one service and one that can trace a change across an entire microservices estate in a single run.\n\nTo add repositories to an existing environment, extend the same creation payload from Step 3 with an array instead of a single repository string, then rebuild:\n\n```\ncurl --request POST \\\n  --url 'https://api.cursor.com/v1/environments' \\\n  -u $CURSOR_API_KEY: \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"name\": \"org-wide-migration\",\n    \"repositories\": [\n      \"github.com/your-org/service-a\",\n      \"github.com/your-org/service-b\",\n      \"github.com/your-org/shared-libs\"\n    ]\n  }'\n```\n\nRemember that the 300-repository cap applies per environment, not per account, so a monorepo-of-repos setup with dozens of independently versioned services can approach that ceiling faster than it looks at first glance. Split genuinely unrelated projects into separate environments rather than piling everything into one, both to stay under the cap with headroom and because a narrower environment is easier for an agent to reason about correctly.\n\n## Step 9: Build and Share an Interactive Agent Canvas\n\nCanvases are the most visible change in this release for anyone who isn’t deep in the API. Instead of returning only a diff or a wall of log output, a Cloud Agent can now build an interactive artifact as part of its work, a dashboard, a rendered UI preview, or a data visualization, depending on what the prompt asked for.\n\nYou don’t request a canvas through a separate flag. It’s something the agent produces when the task calls for it, the same way it decides whether to open a PR or just report findings. Once a run finishes, you can list the artifacts it produced through the API:\n\n```\n{\n  \"items\": [\n    { \"path\": \"artifacts/screenshot.png\", \"sizeBytes\": 12345, \"updatedAt\": \"2026-04-13T18:45:00.000Z\" }\n  ]\n}\n```\n\nRequesting a specific artifact returns a short-lived, presigned URL rather than the file itself, which keeps large build outputs off your own API responses:\n\n```\n{\n  \"url\": \"https://cloud-agent-artifacts.s3.us-east-1.amazonaws.com/...\",\n  \"expiresAt\": \"2026-04-13T19:00:00.000Z\"\n}\n```\n\nOnce a canvas is finished, Cursor lets you share it with your team by sending its link directly, so a teammate without API access, or even without a Cursor account, can view the result in a browser. That’s a meaningfully lower bar than asking a non-technical stakeholder to read a raw diff.\n\n## Step 10: Enable Remote Control From Your iPhone\n\nRemote Control is the feature that bridges local and cloud execution rather than forcing a choice between them. It lets you see and reply to agents running locally on your own machine from the Cursor iOS app, which matters for the common case where an agent is running against a local dev environment that doesn’t have a cloud equivalent yet.\n\nTurn it on from Cursor’s desktop settings under Remote Control, pair your phone through the same account, and you’ll start receiving a push notification whenever a local agent needs input or finishes a task. There’s also a “Keep this computer awake” setting worth enabling if you plan to step away from your desk mid-run, since a local agent stops making progress the moment the host machine sleeps, no matter how good your phone’s connection is.\n\n## Step 11: Install an Origin App Marketplace Integration\n\nThe Origin App Marketplace is the piece that connects Cloud Agents to the rest of your toolchain. It launched with more than 20 integrations, including Cloudflare, Linear, Sentry, and Socket Security, and opened to public submissions shortly after, so the catalog is likely to keep growing past whatever number is current by the time you read this.\n\nInstalling one from Cursor’s dashboard under Integrations connects that service’s API to your agent’s available tools, meaning a prompt like “file a Linear ticket for this bug and link the PR” becomes something an agent can actually execute rather than just suggest. If you’re deciding whether to build a custom integration yourself or lean on what’s already in the marketplace, that’s the same build-vs-buy calculus that shows up in plenty of other infrastructure decisions, including when teams weigh a managed [scraping API service](https://shattered.io/goproxies-scraping-api-review/) against maintaining their own scraping stack in-house. The marketplace route is almost always faster to start with, and building your own only pays off once your integration needs something the catalog genuinely can’t do.\n\n## Step 12: Turn On Rollouts, Security Review, and Usage Tracking\n\nRollouts and Security Review, both released September 23, 2026, are the two bots Cursor built to catch problems after an agent’s code ships, not just before. Rollouts monitors deployed changes and reports whether an environment looks healthy, shows regressions, or is inconclusive. Security Review checks pull requests for exploitable issues such as injection flaws, authentication bypasses, and leaked secrets. Both are available on Teams and Enterprise plans, and both are worth enabling before you let Cloud Agents merge anything without a human in the loop.\n\nFor cost visibility once agents are running regularly, the SDK’s usage methods report token usage, billed cost, and a per-run cost breakdown, which is the fastest way to catch a runaway agent before it shows up as a surprise on your invoice.\n\n``` js\nconst usage = await client.agents.getUsage(\"bc-00000000-0000-0000-0000-000000000001\");\nconsole.log(usage.tokens, usage.billedCost, usage.perRunCost);\n```\n\nCursor also reported changes across its agent stack that reduced token costs for longer agent runs by 7% without reducing agent quality, announced the same week as Rollouts and Security Review. That’s a modest number on its own, but it compounds quickly once dozens of agents are running daily against a 300-repository environment.\n\n## Securing API Keys and Environment Secrets\n\nEvery example in this tutorial has used a single environment variable for the API key, which is fine for a personal demo but not how a team should run this in production. Scope keys as narrowly as the API allows: a key used only by your CI pipeline to create and manage environments shouldn’t also have permission to read every other team’s agent runs. Rotate a key immediately when anyone who had access to it leaves the team, rather than waiting for a scheduled rotation cycle to catch up.\n\nEnvironment secrets, the credentials your agent needs to actually run your project, deploy database access, third-party API tokens, and the like, deserve the same treatment. According to Cursor’s current API documentation, the Environments API’s scope extends to managing these environment secrets directly, rather than requiring you to bake them into `environment.json` or your repository itself. Use that mechanism instead of committing a credential to a config file you’ll forget is tracked in version control six months from now.\n\nThis is also where Step 12’s Security Review bot earns its place in the pipeline rather than being an optional extra. Since it checks every pull request a Cloud Agent opens for exploitable issues including leaked secrets, it functions as a second check on exactly the mistake this section is trying to help you avoid in the first place, an agent that accidentally pastes a credential into a commit because a prompt asked it to “just get this working.”\n\nThe least-privilege principle that runs through most of the [OWASP Top 10](https://shattered.io/owasp-top-10-nodejs/) applies just as directly to an agent’s API key as it does to a human user’s. An agent that only ever needs to open pull requests against one repository shouldn’t hold a key scoped to every environment your organization has created. If you’re setting up Cloud Agents for a team for the first time, it’s worth deciding on a key-scoping policy before the first environment goes live, rather than retrofitting one after a dozen scripts already depend on a single shared key with broad access.\n\n## Common Pitfalls When Running Cloud Agents at Scale\n\n- **Skipping the spending limit step.** Cloud Agents require on-demand billing enabled and a spending limit set before the first launch. Skip it, and your first API call fails with a billing error that has nothing to do with your actual code.\n- **Treating environment.json as a one-time setup.** Builds are now automatic and mandatory for non-draft environments, so a stale install command silently breaks every new agent run until someone updates the file.\n- **Assuming the Environments API is fully stable.** It’s public beta as of October 2026, which means endpoints and response shapes can still change before general availability.\n- **Forgetting the 300-repository cap is per environment, not per account.** A sprawling multi-service setup can approach that ceiling faster than expected if everything lives in one environment.\n- **Mixing commit-reference conventions across team scripts.** Short commit IDs now auto-resolve to the full commit, but if half your scripts still pass full 40-character hashes out of habit, debugging which convention a given failure came from wastes time.\n- **Sharing a canvas link without checking its audience.** A finished canvas is accessible to anyone with the link, so confirm it isn’t going somewhere outside your organization before you send it.\n- **Confusing the Cloud Agents API v1 with the Environments API.** They’re two related but separate beta surfaces with different object models (agents and runs versus environments and builds), and their docs pages aren’t interchangeable.\n\n## Troubleshooting Guide\n\nMost of the issues below come straight from Cursor’s own community forum, where developers have been reporting friction points as fast as the new API surface exposes them. A reasonable debugging order for any Cloud Agent problem: check the environment’s build log first, since a surprising number of agent failures trace back to a build that quietly warned rather than failed outright, then check Cursor’s status page and forum for a matching report before assuming the bug is unique to your setup, and only then open a support ticket once you’ve ruled out a known, already-tracked issue.\n\n| Symptom | Likely cause | What to try | \n|---|---|---|\n| API-created agent returns `usage_limit_exceeded` despite included usage remaining | Reported after the move to consolidated Cursor/Grok billing plans in October 2026 | Check your plan’s migration status in billing settings before assuming your account is actually out of usage | \n| Environment build warns instead of failing cleanly | Default-on builds now surface non-fatal issues that can still break an agent run | Read the build log before launching an agent against that environment | \n| `environment.json` rejected with a vague error | Older parser versions didn’t support comments or trailing commas | Update to a current CLI version, since the parser improved on October 20, 2026 to pinpoint the exact parse failure | \n| Agent stuck on “Planning next moves” with zero tool calls | Reported forum issue where the environment is running but the model produces no output | Restart the environment and resubmit, and if it recurs, check Cursor’s status page and forum before assuming it’s your prompt | \n| Short, narrowly scoped prompts fail within the first few messages | Forum reports describe terse “engineering-shaped” prompts dying at kickoff with no tool calls | Add more explicit context to the prompt rather than assuming brevity will be interpreted correctly | \n| Mid-run steering doesn’t interrupt a cloud agent the way it does locally | Cloud runs reportedly treat a steering call as a follow-up message rather than a live interrupt | Write prompts assuming you can only follow up, not steer mid-run, until Cursor documents parity with the local SDK | \n| Can no longer disable environment builds | Builds became effectively mandatory for non-draft environments as of October 20, 2026 | Use a draft environment for fast iteration where a full build isn’t needed yet | \n| Usage dashboard and billed cost don’t reconcile | A [forum thread](https://forum.cursor.com/t/bug-help-other-models-hits-100-while-usage-export-at-published-api-rates-only-reconstructs-65-how-to-reconcile-the-meter/172012/48) describes a usage-export meter reconstructing only about 65% of reported usage against published API rates | Cross-check `agent.getUsage()` output against your account’s billing export, and raise a support ticket if the gap persists | \n| Remote Control stops responding after your laptop sleeps | The host machine went to sleep mid-run, which pauses any local agent regardless of phone connectivity | Enable “Keep this computer awake” in Remote Control settings before starting a run you plan to step away from | \n\n## Advanced Tips for Production Cloud Agent Pipelines\n\nOnce the basic loop works, a few adjustments make the difference between a demo and something a team can depend on daily.\n\nPin environment creation to your CI pipeline instead of running it ad hoc from a developer’s terminal. Since the Environments API is a standard REST interface, a step that calls `POST /v1/environments` on every new service repository keeps environment definitions consistent and versioned the same way your infrastructure-as-code already is.\n\nModel choice matters more than it might seem once you’re running agents regularly. xAI’s Grok 4.7, released September 21, 2026 and described by the company as its most capable model for long-running coding and knowledge work, launched directly inside Cursor and Grok Build the same day, alongside the standard xAI API. It’s documented with a 500,000-token context window and configurable reasoning levels from low to xhigh, which makes it a reasonable default for agents working across a large, multi-repository environment where context length is the limiting factor rather than raw reasoning depth. You can review the [available agent tools](https://docs.x.ai/developers/tools/overview?ref=thelgtm.dev) xAI documents for Grok models before deciding which one to route a given environment’s agents through.\n\n### Separate draft and production environments\n\nCreate a draft environment for every exploratory agent run and promote only the configurations that work into a non-draft environment. Since non-draft environments now build automatically on every change, this keeps your CI-facing environments stable while you iterate freely on the draft side.\n\n### Treat canvases as disposable, not archival\n\nCanvas artifact URLs are short-lived and presigned, by design. If a canvas result needs to live somewhere permanently, for a compliance record or a retrospective, export it or screenshot it rather than relying on the link remaining valid past its stated expiry.\n\n### Plan for parallel environments, not just bigger ones\n\nIt’s tempting to treat the new 300-repository ceiling as a reason to build one enormous environment covering an entire organization’s codebase. In practice, several smaller, purpose-built environments running agents in parallel tend to finish faster and fail more predictably than a single sprawling one, since a build problem in any one repository can hold up every agent waiting on that environment’s shared build. Reserve the large, multi-repository environments for tasks that genuinely need to reason across many services at once, like the cross-application migration Navan ran, and keep routine, single-service work in smaller, dedicated environments that build and start faster on their own.\n\n## The Complete Working Project\n\nPutting every step together, here’s a single script that creates an environment, waits for its first build, launches an agent, and prints the run’s usage once it completes. Save it as `run-cloud-agent.sh` and adjust the repository and prompt for your own project.\n\n``` bash\n#!/usr/bin/env bash\nset -euo pipefail\n\nBASE=\"https://api.cursor.com/v1\"\nAUTH=\"-u ${CURSOR_API_KEY}:\"\n\nENV_ID=$(curl -s --request POST \"$BASE/environments\" $AUTH \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"name\":\"ci-migration\",\"repository\":\"github.com/your-org/your-repo\"}' \\\n  | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"id\"])')\n\necho \"Environment created: $ENV_ID\"\n\nAGENT_RESPONSE=$(curl -s --request POST \"$BASE/agents\" $AUTH \\\n  -H 'Content-Type: application/json' \\\n  -d \"{\\\"environmentId\\\":\\\"$ENV_ID\\\",\\\"prompt\\\":\\\"Run the test suite, fix any failing tests, and open a PR.\\\"}\")\n\nRUN_ID=$(echo \"$AGENT_RESPONSE\" | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"run\"][\"id\"])')\necho \"Agent run started: $RUN_ID\"\n\nnode stream-run.mjs \"$RUN_ID\"\n```\n\nPair it with the streaming snippet from Step 7 saved as `stream-run.mjs`, and you have a complete loop: create, build, launch, stream, and report, all driven from one shell script you can drop into a CI job or a scheduled task. From here, the natural next step is wrapping this script behind a webhook so a merged PR or a filed Linear ticket can trigger a Cloud Agent automatically, which is exactly what the Origin App Marketplace integrations from Step 11 are built to support.\n\nTreat this script as a starting point rather than a finished tool. A few extensions are worth building before you trust it with anything beyond a demo repository: reusing an existing environment ID instead of creating a new one on every run, once you’ve confirmed the same environment can safely handle repeated agents, checking the build status from Step 5 before launching an agent so you fail fast on a broken build instead of waiting for the agent itself to hit the same problem, and logging each run’s ID to a file or a simple database so you can look up what an agent did days later without digging through chat history. None of these require more than the endpoints already covered in this tutorial, just a bit more error handling around them than a fifteen-line demo script needs.\n\nFor more on how the coding-tools landscape keeps shifting underneath these kinds of pipelines, our [coding and developer tools coverage](https://shattered.io/category/software/) tracks these releases as they land, which is worth a bookmark given how fast Cursor alone has shipped changes this quarter.\n\n## Frequently Asked Questions\n\n**What is the Cursor Environments API?**\n\nIt’s a public beta API that lets developers programmatically create and manage the cloud environments that Cursor’s Cloud Agents run in, rather than configuring them only through the dashboard.\n\n**Is the Environments API generally available yet?**\n\nNo. As of this writing it remains in public beta, which means its endpoints and response formats can still change before Cursor marks it generally available.\n\n**How many repositories can one environment include?**\n\nUp to 300, following the October 16, 2026 update. That cap applies per environment, not per account, so large organizations typically split unrelated projects across multiple environments.\n\n**Do I need to enable billing before launching a Cloud Agent?**\n\nYes. Cursor requires on-demand billing to be enabled and a spending limit set before your first Cloud Agent launches, regardless of how much included plan usage you have left.\n\n**What is Grok 4.7, and can I use it inside Cursor?**\n\nGrok 4.7 is xAI’s model for long-running coding and knowledge work, released September 21, 2026. It’s available inside Cursor and Grok Build, billed through those plans rather than the public xAI API.\n\n**What do Cursor’s current paid plans cost?**\n\nCursor’s pricing page lists Premium at $30/month ($300/year), Super at $100/month ($1,000/year), and Ultra at $200/month ($2,000/year), alongside an $8/month Plus tier limited to Grok-only models.\n\n**Can I control a local Cursor agent remotely from my phone?**\n\nYes. Cursor’s Remote Control feature lets you see and reply to agents running locally on your own machine from the Cursor iOS app, with a setting to keep the host computer awake during the run.", "url": "https://wpnews.pro/news/build-cursor-cloud-agents-12-steps-90-min-2026", "canonical_source": "https://shattered.io/build-cursor-cloud-agents-2026/", "published_at": "2026-10-21 23:34:35+00:00", "updated_at": "2026-10-21 23:40:34.594298+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products", "artificial-intelligence"], "entities": ["Cursor", "Environments API", "Cloud Agent Canvases", "Origin App Marketplace", "Navan", "Stack Overflow", "Gartner", "OpenAI"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/build-cursor-cloud-agents-12-steps-90-min-2026", "markdown": "https://wpnews.pro/news/build-cursor-cloud-agents-12-steps-90-min-2026.md", "text": "https://wpnews.pro/news/build-cursor-cloud-agents-12-steps-90-min-2026.txt", "jsonld": "https://wpnews.pro/news/build-cursor-cloud-agents-12-steps-90-min-2026.jsonld"}}