Cursor 3.4 Cloud Agent Environments: Setup Guide for Multi-Repo and Private Registry Workflows (May 2026)

Cursor 3.4 shipped on May 13, 2026, and the most significant change for engineering teams is one that doesn't show up in tab-complete benchmarks: cloud agents now run inside explicitly defined development environments. Before 3.4, a cloud agent inherited whatever happened to be on the host. Now you define the repos, the Dockerfile, the secrets, and the permissions. The agent sees exactly what you configure. Nothing else.

This guide walks through the full setup. We're covering multi-repo workspaces, private npm and PyPI registries via Dockerfile build secrets, environment versioning, and parallel sessions. If you're running a solo project, the single-repo path is faster to configure. If your agents touch two or more repos, skip straight to Step 3.

What changed in Cursor 3.4

From implicit environments to explicit configuration

Before 3.4, cloud agents ran against whatever the environment happened to contain. That was fine for small teams with uniform setups. It breaks down the moment you're running a parallel agent fleet or you have a private package registry that agents need to reach.

3.4 makes the environment a first-class configuration object. You define it once. Every agent session that runs inside it gets the same setup. Rebuild the environment after a Dockerfile change and every subsequent session picks up the new state.

The four things you define: repos, Dockerfile, secrets, permissions

Each environment definition has four parts:

Repos: one or more repositories cloned into the environment at specified branches or commits
Dockerfile: the image build definition, with optional build secrets for private registries
Secrets: environment-scoped credentials that agents can read during sessions but that are invisible from other environments
Permissions (egress): what agents can reach outside your network

That's the full surface area. The interactive setup process walks you through each one in order.

Why this matters for teams running parallel agent fleets

Credential leakage between parallel environments was a real risk before 3.4. A secret defined at the host level was potentially visible across all agent sessions running on that host. The new scoping model contains secrets at the environment boundary. A secret for your staging environment doesn't bleed into your production environment, even if both run on the same underlying infrastructure.

The 70% build-time reduction on cached layers is operationally significant too. When you're iterating on a Dockerfile and spinning up environments multiple times a day, that matters.

Step 1 - Open the Environments panel and create your first environment

Where to find the panel in Cursor 3.4

Open Cursor and navigate to Settings > Cloud > Environments. If you're on a Team or Business plan, you'll see both team-level and project-level environment slots. The panel shows existing environments, their version history, and a button to create a new one.

You can also reach environments from the cloud agents web interface at cursor.com/agents. The panel there mirrors what you see in the desktop app.

Naming and scoping: team-level vs. project-level environments

Team-level environments are shared across projects. They're the right choice for a standard build image your whole engineering org uses. Project-level environments are scoped to a specific repository group. Use those when one project's dependencies or secrets should stay isolated from others.

Name environments descriptively. api-backend-staging tells you more than env-2 when you're looking at a list of six environments and need to roll one back at 11pm.

What the interactive setup process asks you

Cursor's environment setup isn't a blank form you fill in all at once. It's a guided session. As you configure, Cursor surfaces missing credentials, asks clarifying questions, and validates the setup before the first agent session runs.

The typical sequence:

Name and scope the environment
Add repositories (URLs and target branches)
Point to a Dockerfile or choose a base image
Add build secrets if the Dockerfile references private registries
Set egress rules
Run the validation step

If validation fails because a secret is missing, Cursor tells you which one. It doesn't silently fall back to a broken state.

Step 2 - Configure your Dockerfile and build secrets

Pointing Cursor at an existing Dockerfile

In the environment settings, set the Dockerfile path relative to the repository root. If your Dockerfile lives at infra/docker/Cursor.dev.dockerfile, that's the path you enter. Cursor uses that file to build the agent image.

If you don't have a Dockerfile yet, Cursor can inspect the repositories and generate one. The generated file is a starting point, not a finished artifact. Review it before saving.

Adding build secrets for private npm or PyPI registries

Build secrets let agents install from private registries without exposing credentials in the image layer. The secret value is injected at build time, used by the RUN instruction that runs your install command, and then dropped. It never ends up baked into the final image.

Here's the pattern for a private npm registry:

# syntax=docker/dockerfile:1.4
FROM node:20-slim AS base

WORKDIR /workspace

# Copy dependency manifests first for layer caching
COPY package.json package-lock.json ./

# Mount the npm token as a build secret; install; secret is not in the layer
RUN --mount=type=secret,id=npm_token \
    npm config set //registry.npmjs.org/:_authToken="$(cat /run/secrets/npm_token)" && \
    npm ci --ignore-scripts && \
    npm config delete //registry.npmjs.org/:_authToken

COPY . .

RUN npm run build

In the Cursor environment settings, you add a build secret named npm_token and paste your registry token. Cursor injects it via --secret at build time. The token is not visible in docker history on the resulting image.

For a private PyPI registry, the pattern is the same structure:

# syntax=docker/dockerfile:1.4
FROM python:3.12-slim AS base

WORKDIR /workspace

COPY requirements.txt ./

RUN --mount=type=secret,id=pypi_token \
    pip install \
    --extra-index-url "https://$(cat /run/secrets/pypi_token)@your-registry.example.com/simple/" \
    -r requirements.txt

COPY . .

Add pypi_token as a build secret in the environment settings panel alongside any other secrets you need.

How layer caching works now (and why cached builds are 70% faster)

Cursor's changelog for 3.4 states it directly: only the updated layers of your image rebuild when you change the Dockerfile. Builds that hit the cache run 70% faster.

The practical implication is that you should structure your Dockerfile to put slow, rarely-changing steps early. Dependency installs go before application code copies. A change to your application source triggers a rebuild only from the COPY . . layer downward. The dependency install layer stays cached.

# Good layer order: slow steps first
COPY package.json package-lock.json ./   # install layer - rarely changes
RUN --mount=type=secret,id=npm_token \
    npm ci --ignore-scripts              # stays cached unless deps change

COPY . .                                 # source layer - changes often
RUN npm run build                        # rebuilds from here on source changes

What happens when the Dockerfile fails to build

Cursor does not silently fall back to a base image and let the agent run anyway. If the Dockerfile build fails, the environment setup surfaces the error in the panel and blocks the session from starting. You see the build log, fix the issue, and trigger a rebuild.

A build failure on a secret reference usually means the secret name in the Dockerfile doesn't match the name in the environment settings. Check the id= value in your --mount=type=secret instruction against the secret name in the panel. They must be identical.

Step 3 - Add repositories to the environment

Single-repo setup: the straightforward path

Click "Add repository," paste the repo URL, choose a branch, and optionally pin to a specific commit. That's the complete single-repo setup. The agent clones this repo into the environment at session start.

Multi-repo setup: adding a second repo without creating a merge conflict risk

Cursor 3.4 clones each additional repository into its own subdirectory inside the environment. A backend API repo and a frontend template repo sit at separate paths. The agent can read and write to both without either repo's history interfering with the other.

The .cursor/environment.json config shape for a multi-repo environment looks like this:

{
  "version": "1",
  "repos": [
    {
      "url": "https://github.com/your-org/api-backend",
      "branch": "main",
      "path": "api-backend"
    },
    {
      "url": "https://github.com/your-org/frontend-template",
      "branch": "main",
      "path": "frontend-template"
    }
  ],
  "dockerfile": "infra/docker/Cursor.dev.dockerfile",
  "secrets": ["npm_token"],
  "egress": {
    "allow": ["github.com", "registry.npmjs.org"]
  }
}

The path field controls where each repo lands in the workspace. With this config, the agent works inside a filesystem that looks like:

/workspace/
  api-backend/
  frontend-template/

Cursor reads the .cursor/environment.json from the primary repo and builds the environment accordingly. The UI panel reflects this config and lets you edit it there without touching the file directly.

How the agent navigates between repos in the same session

The agent treats the two repos as sibling directories. It can read files in frontend-template/, make changes there, switch to api-backend/, and open a PR in each. No manual switching. No mid-session context loss.

Git worktree isolation keeps changes in each repo's history separate. An agent working on a feature that touches both a backend endpoint and a frontend component can stage and commit changes in each repo independently within the same session.

Step 4 - Start a cloud agent session inside the environment

Launching a session from an issue or a direct prompt

From the Cursor desktop app or cursor.com/agents, select the environment from the session launch dropdown. You can attach a GitHub issue, a Linear ticket, or type a direct prompt. The environment you pick determines what the agent can see and do.

You can also kick off a session from the Slack or GitHub integrations Cursor ships. The environment selection happens either via a slash command parameter or through a default environment configured in the integration settings.

What the agent can and cannot do inside the environment

Inside the environment, the agent can:

Read and write files in any cloned repository
Run build and test commands defined in the Dockerfile or startup scripts
Access secrets scoped to this environment
Reach external URLs listed in the egress allow-list

The agent cannot:

Access secrets from any other environment
Reach external hosts not in the egress allow-list
Modify the environment configuration itself (that's a human action in the settings panel)

How secrets scoping works: what the agent sees vs. what other environments see

Each environment has its own secrets store. A secret named npm_token in environment A is not readable from environment B, even if both environments run on the same cluster. The scoping is enforced at the environment boundary, not at the session level.

This is the feature that makes parallel agent fleets safe to run. An agent doing work against staging credentials cannot touch production credentials, because those secrets live in a different environment and the agent never crosses that boundary.

Environment versioning and rollback

How to view the version history of an environment

Every time you save a change to the environment configuration, Cursor creates a new version. Open the environment in the settings panel and click "Version history." You'll see a list of versions with timestamps and the identity of whoever made each change (team-level audit logging records all modifications).

Each version entry shows a diff of what changed: which secrets were added or removed, which repos were added or changed, whether the Dockerfile changed.

Rolling back after a bad agent-driven change

Environment configurations don't change themselves mid-session. Agent sessions run inside environments; they don't modify the environment definition. So a rollback scenario is always human-triggered: someone updated the environment and the agents started failing.

To roll back, open the version history, select the last known-good version, and click "Restore." The environment rebuilds from that version's Dockerfile. Subsequent sessions use the restored configuration.

# Trigger a manual environment rebuild via the Cursor CLI after a config change
cursor env rebuild --environment api-backend-staging

The cursor env rebuild command forces a full rebuild even if Cursor's caching layer would otherwise skip unchanged layers. Run this after a Dockerfile edit to confirm the build succeeds before the next agent session picks it up.

When to create a new environment version vs. edit in place

Edit in place when you're making an iterative change that's easy to reverse: adding a repo, updating a branch, adding a secret. Create a new environment (rather than versioning the existing one) when you're making a structural change, like switching from a Node.js base image to a custom one, that you might want to run in parallel with the old setup while you verify agents behave correctly.

Running parallel sessions in the same environment

Two agents, one environment: how worktree isolation prevents conflicts

Cursor uses Git worktrees to isolate parallel sessions running against the same environment. Each session gets its own worktree. Two agents running simultaneously inside the same environment are each working on their own branch without seeing each other's uncommitted changes.

The environment itself (the Docker image, the installed dependencies) is shared. Only the working-tree state is isolated per session.

A concrete example: one agent on a backend fix, one on a docs update

Here's a scenario we've run against the api-backend + frontend-template multi-repo setup:

Input: Two sessions launched simultaneously inside the api-backend-staging environment.

Session A prompt: "Fix the rate-limiting bug in api-backend/src/middleware/rate-limit.ts referenced in issue #234."
Session B prompt: "Update the API changelog in frontend-template/docs/api-changelog.md to reflect the v2.3 endpoint changes."

Expected output:

Session A opens a branch fix/rate-limit-234 in api-backend, makes changes to the middleware file, runs tests, and opens a PR. Session B opens a branch docs/api-changelog-v2.3 in frontend-template, edits the changelog, and opens a separate PR. Neither session touches the other's files. Both PRs show up in the Cursor sessions panel once the agents complete.

This is the core value of the multi-repo + parallel session combination: work that previously required two developers coordinating on separate machines now runs as two concurrent agent sessions sharing a common build environment.

Egress scoping: controlling what agents can reach outside your network

The egress.allow list in the environment config controls outbound network access for agent sessions. An agent that only needs to reach GitHub and your npm registry gets exactly those two hosts. No open egress.

For internal tooling that agents need to reach (internal artifact registries, private documentation servers), add those hostnames to the allow-list. Agents cannot route around the egress rules by using alternative protocols; the controls sit at the network layer, not the application layer.

Cursor 3.4 vs. GitHub Copilot app vs. Claude Code

These tools aren't competing for the same use case. They're optimized for different ends of the development workflow.

Cursor 3.4 for teams with Docker-based multi-repo setups

Cursor 3.4 is the right call when you need Dockerfile-based environment isolation, private registry access, and the ability to run parallel agent sessions across multiple repos without credential leakage.

GitHub Copilot app for GitHub-native teams that want PR-to-merge automation

The GitHub Copilot app, which launched in technical preview on May 14, 2026, is the right call when your workflow ends in a GitHub PR and you want Agent Merge to handle review feedback and merge follow-through automatically. It's GitHub-native: sessions start from issues and PRs, and the output is a PR your existing review process handles normally. More detail in our GitHub Copilot app setup guide.

Claude Code for engineers who want terminal-native BYOK control

Claude Code is the right call when you want full bring-your-own-key control, no cloud infrastructure dependency, and a terminal-native workflow where you direct every step. There's no managed environment layer; you bring the context, you run the commands.

The workflow that combines all three without confusion

We've seen teams run all three without confusion by drawing a clear boundary: Cursor 3.4 for long-running background tasks in isolated environments, Claude Code for local exploratory work and prototyping, GitHub Copilot app for the final PR automation and merge sequence. Each tool owns one phase of the loop.

For a direct feature comparison, see our Cursor vs. Copilot breakdown.

FAQ

Do I need a Team or Business Cursor plan to use cloud agent environments?

Yes. Cloud agent environments are a Team and Business feature. The personal Pro plan gives you access to cloud agents, but environment configuration (multi-repo, custom Dockerfile, secrets scoping) requires a team seat. Check Cursor's pricing page for current plan details.

Can I reuse an environment across multiple projects?

Yes, if the environment is scoped at the team level rather than project level. Team-level environments are selectable from any project's session launch screen. Project-level environments are tied to a specific project and can't be selected from outside it.

Do build secrets ever appear in agent session logs?

No. Build secrets are injected at image build time and dropped before the image is finalized. Agent session logs capture what happens at runtime inside the container, where secrets are no longer present. The secrets are never written to disk in the final image layer. If your agent needs a runtime secret (an API key for a service it calls during a session), that's a separate runtime secret you configure in the environment's secrets panel, not a build secret.

How many parallel sessions can run inside one environment?

Cursor's documentation doesn't publish a hard cap on parallel sessions per environment. In practice, the limit is determined by the worktree isolation overhead and your team's compute allocation on the plan. We've run two concurrent sessions in the same environment without issue. For large fleet deployments, contact Cursor's team directly.

What happens to my environment if I update the Dockerfile?

Updating the Dockerfile creates a new environment version but does not immediately rebuild the running image. The next session you launch from that environment triggers a rebuild. If you want to force a rebuild before the next session, run cursor env rebuild --environment <name> or click "Rebuild now" in the settings panel. Cached layers that haven't changed still build fast.

Cursor 3.4 is the first agentic coding tool to ship explicit environment definition with full Dockerfile support, build-secret injection, and cross-environment secrets isolation in a single release. If you're running any multi-repo agent work or touching private registries, the configuration overhead is minimal and the isolation payoff is real. You can also pair Cline with Cursor environments if you want a local agentic layer that feeds into the same repos your cloud agents work against. Our Cline vs. Cursor comparison covers how those two tools split the work.

Start with a single environment, get one agent session working end-to-end, then add the second repo. Building up incrementally keeps each step easy to debug, and the version history is there if anything goes sideways.