environment.json for Cursor Cloud Agents: Full Reference

It's the config-as-code option for cloud agent environments. Instead of saving an environment in the dashboard, you commit a JSON file at .cursor/environment.json and every agent launched against the repo builds its machine from it. Cursor resolves configuration by first match: this file, then a personal saved environment, then a team saved environment. When the file exists, it wins.

Agents use the configuration at the commit they start from, which is the behavior that makes the file worth committing in the first place. Push a config change to a branch, start an agent from that branch, and you have tested the new environment without touching what the rest of the team runs. The setup guide covers how this fits into the two setup paths; this page is the field-by-field reference.

Cursor's docs give the personal saved environment a specific job: one person tries a configuration out before the team inherits it, and it applies only when the repo has no .cursor/environment.json. Committing the file closes that route for everyone who launches an agent against the repo.

Two people sharing a repo can commit it on day one. On a repo a dozen people launch agents against, I would get the environment stable as a saved environment first and commit the file after a week of nobody editing it.

The published schema defines exactly ten top-level fields, split between the base image (how the machine is built) and the runtime (what runs on it). Fields not in this table don't exist; the schema rejects unknown properties, so a typo like startup fails validation rather than being silently ignored.

Most repos never use most of that table. Both samples Cursor publishes are two fields long, a base image plus an install, and I suspect that is the honest shape of most real configs. The rest arrive one problem at a time. ports shows up the day something outside the container has to reach the dev server, start the day a run needs the Docker daemon up.

Two of these deserve a closer look because their descriptions carry non-obvious detail. The terminals entries take a description field that is displayed to the agent, so it doubles as a prompt: a terminal described as 'Next.js dev server on port 3000' tells the agent what's already running and where. And repositoryDependencies is about access, not cloning: the schema describes it as repos that need to be in the environment's GitHub token, which matters when your build pulls a private sibling repo.

Nothing at the top level is required, incidentally, so an empty {} validates: you get Cursor's default base image and no install step.

Builds split durable preparation from live services. Cursor prepares and activates disk state ahead of an agent run, then starts services and shared terminals when the agent begins. That separation decides where each command belongs.

1. 1Prepare the Build. Cursor starts from the configured base, clones every repository at its default branch, and runs install to completion.
2. 2Snapshot and activate. A successful Build records environment state and repository commits, then becomes the active prepared machine. A failed Build does not replace it.
3. 3Start the agent. Cursor starts the agent from the active Build and runs start for services that must be fresh.
4. 4Open shared terminals. Each configured terminal launches in the workspace's shared tmux session.

The install command must be complete and idempotent because Cursor can run it repeatedly on prepared disk state. A successful Build keeps installed packages, generated files and warmed disk caches. Processes, shell exports and in-memory caches stop at the snapshot, so Docker, databases and tunnels belong in start rather than install.

Idempotent carries more weight than it looks like it should. A later Build can run against prepared disk state, so a script written as though the machine were always new behaves differently the second time through. Keep destructive database setup out of install, and inspect the Build logs and exact commit before changing a config that appears stale.

Here's a Dockerfile-based config exercising most of the schema: a custom image, an idempotent install, Docker started for the run, a dev server the agent can see, and its port exposed.

{
  "name": "web-app",
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "install": "pnpm install",
  "start": "sudo service docker start",
  "terminals": [
    {
      "name": "dev",
      "command": "pnpm dev",
      "description": "Next.js dev server on port 3000"
    }
  ],
  "ports": [{ "name": "web", "port": 3000 }]
}

You would write that version for the reasons the docs give for a Dockerfile: system-level packages, a pinned compiler version, a debugger, a different base OS. Plenty of repos need none of them, and guided setup gets those repos to a working environment in under ten minutes.

The snapshot-based variant is shorter, because the base image is a saved VM instead of a build. This is what you typically commit after agent-driven setup, so the whole team inherits the environment.

{
  "snapshot": "snapshot-20260212-00000000-0000-0000-0000-000000000000",
  "install": "npm install",
  "agentCanUpdateSnapshot": true
}

The schema says agentCanUpdateSnapshot controls whether the agent may update the snapshot and stops there, so before setting that last line true on a repo other people run agents against, watch what one setup run does with the permission.

Most environment.json failures come from a handful of documented sharp edges rather than from the fields themselves. These are the ones worth knowing before you debug a broken setup run.

• Paths split between two roots. build.dockerfile and build.context are relative to .cursor; the install command runs from the project root. Mixing those up is the classic first failure.
• Don't `COPY` the project in your Dockerfile. Cursor manages the workspace and checks out the correct commit itself; a COPY . . bakes a stale tree into the image.
• No secrets field exists. Credentials go in the dashboard's Secrets tab and arrive as environment variables. If your agent can't read one, that's its own fix path.
• Snapshots can fall back. If a snapshot expired, failed or isn't accessible to you, Cursor swaps in the default base image, keeps the rest of the config, still runs install, and shows 'Environment ready (with warnings)'. Roll back deliberately from Version history in the dashboard settings if you need the old version.
• Failed Builds stay inactive. Agents keep using the latest successful active Build while you inspect the failed Build's events, logs and commit SHAs.
• You never get direct machine access. With Dockerfile setup, the image definition is your only lever; there is no SSH into the VM to patch things by hand.
• Layer caching works for you. Changing a Dockerfile rebuilds only the changed layers, so order slow steps first and volatile steps last.

A base snapshot can still expire or become inaccessible. Builds add another protection after that base is resolved: only a successful prepared Build becomes active, and a failure leaves agents on the last successful one. Before the first successful Build, agents use the standard environment startup flow instead.

The Builds tab is now the first place to diagnose that state. It shows the Build status, logs, repository commit, and which Build each agent run used.

If a run behaves like a config you no longer have, check the commit it started from before you check the file. The fix you push afterwards applies to the next agent you start.