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.

One behavior makes it unusually pleasant to work with: agents use the configuration at the commit they start from. Push a config change to a branch, start an agent from that branch, and you've 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.

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.

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.

Every new machine walks the same sequence, and knowing it tells you where each command belongs. The base image comes first, from a snapshot or a Dockerfile build, and the rest layers on top.

1. 1Base environment. The VM boots from your snapshot or from the image built by build.dockerfile. With neither, it's Cursor's default Ubuntu base.
2. 2`install`. The update script runs after the latest changes are pulled. Dependency setup goes here: pnpm install, pip install, bazel build.
3. 3`start`. Long-lived services the run depends on. Many repos skip it entirely.
4. 4`terminals`. Each configured terminal launches in the shared tmux session, in the workspace, visible to both you and the agent.

The install command has a contract: it must be idempotent, because Cursor may run it more than once and on partially cached state. There's a payoff for keeping it fast and repeatable. When install takes more than a few seconds, Cursor snapshots an internal checkpoint afterward and tries to start future agents from it, which is why a plain pnpm install usually means near-instant startups on active repos. Caching is best effort; rarely-used repos start slower.

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 }]
}

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
}

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.
• 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.