Can a self-hosted agent be launched through an API

Support Help
1 
curl --request POST \
  --url https://api.cursor.com/v0/agents \
  -u YOUR_API_KEY: \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": {
    "text": "Add a README.md file with installation instructions",
    "images": [
      {
        "data": "iVBORw0KGgoAAAANSUhEUgAA...",
        "dimension": {
          "width": 1024,
          "height": 768
        }
      }
    ]
  },
  "model": "claude-4.5-sonnet-thinking",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "target": {
    "autoCreatePr": true,
    "branchName": "feature/add-readme"
  }
}'

The interface has no self-managed parameters and can only be a cloud agent

5

Hey, yep, this is supported. In the request body for POST /v0/agents, pass an extra parameter "usePrivateWorker": true, and the run will go to your self-hosted worker instead of a Cursor-hosted VM.

Example:

{
  "prompt": { "text": "..." },
  "model": "claude-4.5-sonnet-thinking",
  "source": { "repository": "https://github.com/your-org/your-repo", "ref": "main" },
  "target": { "autoCreatePr": true, "branchName": "feature/add-readme" },
  "usePrivateWorker": true
}

For this to work, you need:

  • A deployed self-hosted worker connected to your team, see Self-Hosted Pool | Cursor Docs
  • In Team Dashboard > Cloud Agents > Self-hosted Agents, turn on Allow Self-hosted Agents

If you want to force all runs API + Automations + UI to use only self-hosted, there is also a toggle there called Require Self-hosted Agents for All Cloud Agents. There is a known issue with that toggle right now for some teams it does not persist. It is being tracked, and I can’t share an ETA yet. As a temporary workaround, use "usePrivateWorker": true per request. It works independently.

Important: self-hosted Cloud Agents are a Team or Enterprise feature. They are not available on Pro in a personal account. You need a team plan with a configured worker pool.

More details on the same topic are in this thread: this t​hread. If anything does not work, tell me and we will troubleshoot it.