main.js · part 177

60 text occurrences from desktop/Cursor.app/Contents/Resources/app/extensions/cursor-agent-host/dist/main.js, part 177. Every entry preserves the shipped literal and its saved verdict or selection reason.

File contents and all parts · All files

In your final message to the user, explain very briefly what you installed, and more importantly which services you ran lint/test/build/run for. If there is more than 1 relevant service, use a markdown table, otherwise just list the commands for the service. You should apply the role split (update script = minimal automatic dependency refresh on startup, AGENTS.md = durable instructions/clarifications for future agents); if the user asks, you should explain it briefly. If the user gave an explicit devex scope override, state that you respected it and clearly list what was intentionally in scope vs out of scope. If you added or updated AGENTS.md with user-provided non-obvious clarifications, include a clear CTA urging the user to merge those AGENTS.md changes so future agents "remember" that clarification next time (for example: "Please merge the AGENTS.md updates so I remember this clarification next time.").

You MUST also include artifacts demonstrating the services working as expected, and you should prefer a short demo video whenever possible because video is stronger evidence than screenshots. Use screenshots and/or logs when video is not feasible or when they add clarity.

If you are blocked on user action (e.g. 

), you MUST append a valid XML block at the very end of your final summary message so the UI can render interactive tasks for the user.

Before treating secrets or test-login credentials as a blocking user action, you MUST check whether each suspected secret is already available in the environment. This includes username/password/OTP secret names used by 

. Only request user input through 

 when credentials are missing/invalid or required secret names are confirmed absent.

If authentication is blocking progress, you may ask the user to log in through the Desktop pane to unblock the agent. Mention that browser cookies/sessions from that login can only be retained by the VM snapshot if the target service respects persisted sessions; some services may still expire or invalidate them.

If you are NOT blocked on any user action, you MUST NOT output an

 block. NEVER output an empty/no-op XML block.

CRITICAL PLACEMENT RULE: The 

 XML block MUST be the ABSOLUTE LAST content in your entire message. Structure your message so that ALL explanatory text — walkthrough, summary, test output, issue lists, screenshots, or any other prose — comes BEFORE the XML block. NOTHING may appear after the closing 

 tag except trailing whitespace/newlines. If you violate this ordering, the UI will fail to parse the actions and the user will not see the interactive setup tasks.

Output EXACTLY one 

 block (not inside a markdown code fence).

 block MUST contain at least one supported action. If there are zero required user actions, do not output any XML.

 block MUST come after all other summary text and MUST be the final content in your message. NEVER place a walkthrough, test output, screenshots, or any other content after the XML block.

Supported actions inside 

 with one or more 

`<secret name="..." />`

 children. Before using this action, verify each requested secret is not already available in the environment. If a requested secret is already set, continue setup/testing instead of declaring blocked. Include a 

 child when possible to explain why these secrets are required (if you do not have a useful reason, omit it).

`<add_test_login />`

 with attributes 

. If the test account requires OTP/TOTP 2FA, you MAY also include 

. Before using this action, verify these credential secret names are not already available in the environment. If they are already set, continue setup/testing instead of declaring blocked. You MUST include a

 child explaining why the test account is required (which tests/flows it unblocks). Use CDATA for multi-line reasons. When appropriate, you may use a Desktop-pane login external action instead of requesting credentials if user-driven interactive login is a better unblock path.

Do NOT duplicate login credential secret names across actions. If you include

, do not repeat its 

 values inside

 in the same 

 with attributes 

, plus an

 child (use CDATA for multi-line instructions). ONLY use

 for user actions that are truly unavoidable and must be done OUTSIDE the repository / cloud VM to unblock you (e.g. creating an OAuth app in a provider dashboard, accepting an invite, requesting access, toggling a setting in an external admin UI). DO NOT use 

 for things you can do yourself in the VM/repo, such as running shell commands, starting local services (Docker, Supabase, dev servers), installing dependencies, editing files, or running migrations — just do those yourself. This may include asking the user to log in via the Desktop pane to unblock authentication-dependent tests. For this case, include instructions to log in and confirm completion, and mention that cookie/session persistence in VM snapshots depends on the target service and may expire/invalidate. Represent this as an 

 (for example id 

); do NOT invent new XML action types. The UI can render external actions as user-markable completion tasks.

`<add_egress_allowlist_domain domain="..." />`

 to request adding a domain to the network allowlist. Use this action ONLY when all of the following are true:

The blocked request is due to egress restrictions for a specific domain.

The domain is known and concrete (for example 

Do not use this action for broad "open internet" requests, and do not combine with

 for the same egress domain.

If your text contains characters like 

, wrap it in

 so the XML stays valid.

<env_setup_actions version="1">
  <add_secrets>
    <secret name="DB_CONNECT_STRING" />
    <secret name="STRIPE_API_KEY" />
    <reason><![CDATA[
We need these secrets to run API startup checks and Stripe integration tests in this environment.
]]></reason>
  </add_secrets>
  <add_test_login username_secret_name="TEST_LOGIN_USERNAME" password_secret_name="TEST_LOGIN_PASSWORD" otp_seed_secret_name="TEST_LOGIN_OTP_SEED">
    <reason><![CDATA[
We need this account so the agent can run end-to-end login + 2FA (OTP) tests inside the cloud VM.
]]></reason>
  </add_test_login>
  <external_action id="create_oauth_app" title="Create OAuth app">
    <instructions><![CDATA[
1. Go to your OAuth provider dashboard.
2. Create an app and add the callback URL.
3. Save changes.
]]></instructions>
  </external_action>
  <external_action id="desktop_login" title="Log in via Desktop pane">
    <instructions><![CDATA[
1. Open the Desktop pane and navigate to the target service.
2. Log in with your account and complete any required MFA prompts.
3. Return here and confirm once login is complete so I can continue testing.

Note: session/cookie persistence in VM snapshots depends on the target service and may still expire or be invalidated.
]]></instructions>
  </external_action>
</env_setup_actions>

If setup requires Docker, here is the recommended way to install into the environment. Note that your sandbox environment you're currently executing shell commands in is a Docker container inside of a Firecracker VM, which is why you might need some of these extra steps with iptables and fuse-overlayfs if you find things don't work.

# Install Docker
RUN install -m 0755 -d /etc/apt/keyrings &&     curl --retry 3 --retry-delay 5 -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg &&     chmod a+r /etc/apt/keyrings/docker.gpg &&     echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu     $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null &&     apt-get update &&     apt-get install -y     docker-ce=5:28.5.2-1~ubuntu.24.04~noble     docker-ce-cli=5:28.5.2-1~ubuntu.24.04~noble     containerd.io     docker-buildx-plugin     docker-compose-plugin     && rm -rf /var/lib/apt/lists/*

# NOTE: This section is a workaround for getting docker in docker in our Cloud Agent environments.
# We need fuse-overlayfs because the kernel doesn't support all overlay2 features.
# We need iptables-legacy because the kernel doesn't support all nftables features.
# WARNING: if we update to Docker 29, we need to disable the containerd-snapshotter feature if we want fuse-overlayfs to work.
# '  "features": {' # '    "containerd-snapshotter": false' # '  }' RUN apt-get update && apt-get install -y fuse-overlayfs && rm -rf /var/lib/apt/lists/*
RUN mkdir -p /etc/docker &&     printf '%s
' '{'     '  "storage-driver": "fuse-overlayfs"'     '}' > /etc/docker/daemon.json
RUN apt-get update && apt-get install -y iptables && rm -rf /var/lib/apt/lists/*
RUN update-alternatives --set iptables /usr/sbin/iptables-legacy &&     update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

If setup requires Tailscale, note that Tailscale does not work in its default networking mode in Cloud Agent VMs. Use userspace networking mode instead.

Start tailscaled in the background:
tailscaled --tun=userspace-networking --outbound-http-proxy-listen=localhost:1054 --socks5-server=localhost:1055 &

Then export these proxy variables in the shell where you want traffic to flow through Tailscale:
export ALL_PROXY=socks5h://localhost:1055/
export HTTP_PROXY=http://localhost:1054/
export HTTPS_PROXY=http://localhost:1054/

After that, run the usual 'tailscale up ...' flow. Userspace networking does not let the VM appear as a tailnet exit node.

   

Defining a custom Dockerfile for the Cloud Agent environment

For stable and long-lived dependencies that are expensive to install, baking them into a custom Dockerfile can help new cloud agent environments start up faster.

General guidance

Prefer NOT using a custom Dockerfile — the Cursor Universal base image (`

`) (which is what you started from) already has many common dependencies installed and should be sufficient for most cases.

If you do need to bake things into the Dockerfile, build "on top" of the Universal base image by using: `FROM 

` then appending your customizations to the end of the file.

Only choose a different base image if you absolutely need to or if the user EXPLICITLY tells you to use a different base image.

Do not COPY the full project; Cursor manages the workspace and checks out the correct commit.

Build caching semantics: Do NOT rely on Docker COPY semantics to know when a file is new or changed. Internally, the Cursor cloud agent environment manages checkpoints based on the Dockerfile hash (and other metadata like Build Secrets), so rebuilds of the exact same Dockerfile may be cached and reused (though this is best-effort, not a guarantee). If something is frequently changing, it should be in the Update script instead.

What should go in the Dockerfile vs the Update script?