Why is my dockerfile being rebuilt all the time?

[ryanw]

I’ve got an environment.json file setup like this:

{
  "build": {
    "dockerfile": "../.docker/Dockerfile",
    "context": ".."
  },
  "install": "bash .docker/scripts/cloud-agent-install.sh",
  "start": "bash .docker/scripts/cloud-agent-start.sh"
}

It seems to be working fine, but I’ve noticed that my cloud agents will randomly build the docker file (which takes like 5-10 mins), after saying they’re starting from a snapshot. And then they’ll say they’re saving a snapshot (which I’d assume would be used going forward), but the next cloud agent will do the same thing!

Why does the agent not accurately show its setup history?

Bit of a side note, but it’s annoying that the history of the cloud agent setup is silently rewritten to remove the docker build steps once they’re done. The same agent that I shared the image of above shows this once up and running:

No mention of docker, and the timestamps there make it seem like this took about a minute, when it was actually about 10x that.

What are snapshots for in the context of using environment.json / docker?

This screen below shows “setup runs”, but I’m guessing that’s different from snapshots (since they have different IDs)? Why don’t we see the list of all snapshots anywhere? Am I supposed to be putting the snapshot ID in the environment.json file (I see the spec references it)? That seems to defeat the purpose of having automatic snapshots…what am I missing here?

In case it’s related, you can see from the screenshot above that my update script section on the cloud agent environment settings is not set, because I’m assuming that I don’t need it since I’m using the install and start sections on the environment.json file, but maybe that’s causing problems with snapshots?

I don’t want to share the contents of the install and start scripts, and I’ll confess that I’m a little unclear on what should go in which one, and how that might affect the snapshot / docker build issues referenced above. But generally in install I’m running composer and npm install commands, plus installing other packages via different methods. I do start mysql so I can run database migrations, because my thinking was that the snapshot probably captures post-install but pre-start?

Anyway, I feel like I must be missing something here, any help would be appreciated!

[deanrie]

Hey, thanks for the detailed writeup with screenshots. That context helps.

I’ll answer what I can, and I’ll be clear about what I still need to look into.

Why the Dockerfile keeps rebuilding

I can’t give a definitive answer without looking at the specific sessions. The snapshot system is best-effort Setup | Cursor Docs, but what you’re describing, starting from a snapshot and then rebuilding Docker anyway, sounds like it might be a bug, not expected behavior. Can you share a Request ID from a session where this happened? That would let the team check the real snapshot and rebuild flow for your environment.

Setup history being rewritten

Yep, this is confusing. The team knows about the UX issue where setup steps get collapsed after completion. It makes it hard to debug timing and see what actually ran.

Snapshots vs setup runs

From the docs: after your install command finishes, if it took more than a few seconds, Cursor takes an internal checkpoint snapshot and tries to reuse it for future agents. The start command then runs every time after the snapshot is restored.

One thing worth noting: in environment.json the field is called install, but in the UI and in the docs it’s referred to as the update command. Same thing, just inconsistent naming.

About the snapshot ID field in the schema: the full spec https://www.cursor.com/schemas/environment.schema.json mentions it, but it’s not covered in the public docs. From what I’ve seen, with environment.json plus Docker, snapshots are managed automatically and you shouldn’t need to set a snapshot ID manually. But I want to confirm that instead of guessing.

Install vs start

Per the docs https://cursor.com/docs/cloud-agent/setup: install is for dependency setup that can be cached, like composer install or npm install, and it must be idempotent. start is for processes that should stay alive while the agent runs. The dashboard update script being empty is fine since your environment.json takes precedence.

For the MySQL and migrations part, I don’t want to speculate about how snapshots interact with running services. Once I can look at your sessions, I can give a clearer answer.

Next step: if you can grab a Request ID from a cloud agent session that did the unexpected Docker rebuild, drop it here and I’ll escalate to the team.

---

[ryanw]

Sorry for the delay, haven’t been able to reproduce this again, so perhaps something changed on the backend with regard to this? Will post here if starts happening again.

[deanrie]

Hey, thanks for the update.

Glad it’s not happening anymore. It was probably caused by some backend changes related to how cloud agents handle Docker rebuilds and snapshots. That area is being actively worked on right now.

About the UX for the setup step history (when the Docker build steps disappear after finishing), the team is aware and it’s on the radar. No ETA yet.

If the repeated rebuild issue comes back, please send the Request ID from that session. That’ll help a lot with debugging.