I’m trying to use the environment.json configuration for my cloud agents, and I have a docker compose stack that I’m trying to reliably have running before the agent continues with its inference.
The problem I’m running into is that the “start” script in the environment.json is not blocking, and the agent only seems to wait for a few seconds before trying to continue answering the user’s prompt. The start script continues to run in the background though.
Because my startup script seeds my test database, which can take up to 3 minutes to get all the containers up and running, the app is not yet available at the point in time the agent continues with execution.
Is there any reliable way to have the start script (or other) block agent execution until it is fully complete?
This is expected behavior. The start command in environment.json is designed for long-running background processes (like dev servers) and runs detached without blocking agent execution.
For setup that needs to complete before the agent starts working, use the install command instead. install runs synchronously and blocks until it finishes. You could structure it like this:
Where setup.sh handles the blocking work: pulling images, waiting for containers to be healthy, and seeding the DB. Keep start for the long-running process (docker compose) that should stay alive alongside the agent.
One thing to note: if install takes more than a few seconds, Cursor snapshots the result, so subsequent agent starts from the same environment should be much faster. Just make sure your install script is idempotent since it may run on partially cached state.
Alternatively, you can add cloud-specific instructions in an AGENTS.md file telling the agent to verify services are healthy before starting work. This gives you more flexibility if the setup varies per task.
I’ve found that the install script only runs when something in that script or my Dockerfile change. Otherwise it just reuses the snapshot, as you’ve mentioned.
In our case we’re trying to make sure the test database has up to date data in it. We use a bacpac file (sql-server) in our repo, and our QA team changes the contents of that file as they add new tests.
We want to make sure every single agent starts with the latest set of data, so pre baking it into the snapshot is not ideal, since changes won’t automatically be applied without a bump to the install script or Dockerfile.
We have added cloud-specific instructions to our AGENTS.md file to direct it to wait until our “verify” script is successful, and this seems to be working, but it still feels a little risky to not have a solid reproducible startup script for the environment. Especially considering how our AGENTS.md file is growing with all the use-cases we need to capture in it, and further bloating the context.
I’m planning on using an automated agent to do bug reproduction, triggered from a user’s ticket, and if its not reliable in setting up the environment, we’ll spend more time validating its work then if we were confident the environment is consistent.
What would be great for us is to have some sort of flag or something to toggle the blocking nature of the start script.
You’re right — since install gets snapshotted after its first run, it won’t re-run with fresh data on every agent start. For a test database that QA updates via committed bacpac files, that doesn’t work.
Your AGENTS.md approach is actually the closest thing to the recommended pattern right now: use install for cached dependency setup, then use AGENTS.md for commands the agent should run during the session. To keep the file from growing, you can put the cloud-specific setup instructions in a dedicated file (e.g., .cursor/cloud-setup-instructions.md) and reference it from AGENTS.md with a single line. That way the context stays modular.
You’re definitely not the only one with this concern. There’s an existing feature request that asks for exactly this: Background agent should wait for start command to finish in environment.json. Adding your use case there would help our product team gauge demand. We’ll be tracking both threads to help prioritize accordingly.