Is the Cloud Agent start script in Cursor guaranteed to execute on every new agent kickoff?

Support Help
,
1

I’m trying to understand the expected behavior of the Cursor Cloud Agent start script as described in the documentation:
https://cursor.com/docs/cloud-agent#startup-commands

From my understanding, the start script should run when a new cloud agent is initialized.

However, in practice, I’m not seeing the script execute on new agent kickoffs the way I would expect. This makes me unsure whether:

  • The start script is guaranteed to run exactly once per new agent instance

  • It only runs under certain conditions

  • It may be skipped if the agent environment is reused or cached

Here is my current environment.json

{
  "build": {
    "dockerfile": "Dockerfile",
    "context": "."
  },
  "terminals": [],
  "install": ".cursor/scripts/install.sh",
  "start": ".cursor/scripts/start.sh",
  "user": "root",
  "ports": [{
    "name": "api",
    "port": 5501
  }],
  "agentCanUpdateSnapshot": true
}

Can someone clarify:

  1. Is the start script guaranteed to run once for every new cloud agent spin-up?

  2. Under what conditions would it not run?

  3. How can I reliably verify that it executed?

Any insight into the lifecycle behavior of cloud agents would be greatly appreciated.

3

It turns out my start.sh script was throwing an error very early in execution. Because it failed so quickly, it didn’t produce any visible logs, and there were no clear error messages surfaced in the agent environment logs, which made it look like the script wasn’t running at all.